> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect HubSpot Knowledge Base

> Create a HubSpot Private App access token, paste it into Data Sources, and OpenCX pulls your published Knowledge Base articles.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
</Tip>

<Warning>
  Only **published** Knowledge Base articles are synced. HubSpot indexes drafts separately and does not expose them to third-party integrations. Publish articles in HubSpot before expecting them in OpenCX.
</Warning>

## Set up the sync

<Steps>
  <Step title="Create a HubSpot Private App">
    In HubSpot, go to **Settings → Integrations → Private Apps** and create an app. Add the `cms.knowledge_base.articles.read` scope so OpenCX can read full Knowledge Base article bodies through HubSpot GraphQL. See [HubSpot's private apps guide](https://developers.hubspot.com/docs/guides/apps/private-apps/overview).
  </Step>

  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="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 scoped access token from the private app you created above. |
  </Step>

  <Step title="Start the sync">
    Click **Connect**. OpenCX validates HubSpot Knowledge Base GraphQL access, auto-detects your portal ID, and starts a full pull of **published** articles with their full body content. Large knowledge bases take longer.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Published articles appear under **HubSpot Knowledge Base**, each linked to its source URL in your help center.
  </Step>
</Steps>

## What gets synced

<AccordionGroup>
  <Accordion title="Published articles only" icon="file-lines">
    Whole-account pull of articles HubSpot exposes through Knowledge Base GraphQL. Titles, full article bodies, source URLs, and selected HubSpot metadata are stored for retrieval.
  </Accordion>

  <Accordion title="Visibility" icon="eye">
    Published articles with public HubSpot access rules are stored as **public** knowledge. Published articles with restricted HubSpot access rules are stored as **internal** knowledge. Drafts and unpublished articles are **not** pulled and never appear in the index.
  </Accordion>

  <Accordion title="Full refresh, not incremental" icon="arrows-rotate">
    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.
  </Accordion>
</AccordionGroup>

## 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 with `cms.knowledge_base.articles.read` |
| **API used**          | HubSpot GraphQL Knowledge Base (`KB.knowledge_article_collection`)       |
| **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

<CardGroup cols={2}>
  <Card title="HubSpot Knowledge Base overview" icon="hubspot" href="/knowledge/sources/hubspot-kb/overview">
    What this source does and doesn't.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/hubspot-kb/troubleshooting">
    Auth errors, missing articles, slow syncs.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for draft HTML or scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>