Set up the sync
Create a HubSpot Private App
In HubSpot, go to Settings → Integrations → Private Apps and create an app. Any valid access token for the account works — OpenCX uses it only to detect your portal ID. See HubSpot’s private apps guide.
Open Data Sources
Go to AI Training → Data Sources.
Add a HubSpot Knowledge Base source
Click Add source → HubSpot Knowledge Base.
| Field | Example | Where to get it |
|---|---|---|
| Private App Access Token | pat-na1-… or pat-eu1-… | The access token from the private app you created above. |
Start the sync
Click Connect. OpenCX auto-detects your HubSpot portal ID and starts a full pull of published articles from the Site Search index. Large knowledge bases take longer.
Verify in AI Instructions
Open AI Training → AI Instructions. Published articles appear under HubSpot Knowledge Base, each linked to its source URL in your help center.
What gets synced
Published articles only
Published articles only
Whole-account pull of articles HubSpot has published and indexed for site search. Titles, indexed body snippets (LONG mode), and the public article URL are stored for retrieval.
Visibility
Visibility
All synced articles are public — they are published, customer-facing help content. Drafts and unpublished articles are not pulled and never appear in the index.
Full refresh, not incremental
Full refresh, not incremental
Each sync run is a full re-pull with overwrite, so unpublishing or deleting an article in HubSpot removes it from the index on the next successful sync. The cost is that each run is heavier than an incremental pull — adjust the cadence on the connection schedule if you have a very large knowledge base.
Limits
| Value | |
|---|---|
| Streams synced | articles |
| Sync mode | full_refresh_overwrite |
| Sync cadence | Airbyte polling — typically every few hours |
| Credential type | HubSpot Private App access token (portal ID auto-detected) |
| API used | HubSpot Site Search (type=KNOWLEDGE_ARTICLE) |
| Draft handling | Not synced — publish in HubSpot first |
| Multi-account | One HubSpot portal per source |
| Selective scoping | None today — whole published index pulled |
Related Documentation
HubSpot Knowledge Base overview
What this source does and doesn’t.
Troubleshooting
Auth errors, missing articles, slow syncs.
Website crawler
Fallback for draft HTML or scoped subsets.
Connect a knowledge source
All sources.