Skip to main content

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.

OpenCX is moving from HubSpot Private Apps (paste-token) to a HubSpot Public App that connects via OAuth. This page walks through what changes for you and how to migrate.

​
Why migrate

  • Private Apps are HubSpot’s legacy auth path. New features (workflow extensions, granular OAuth scopes) only work on the Public App / OAuth track.
  • One click instead of token paste. No more creating a HubSpot Private App, copying scopes, pasting access tokens, or configuring webhooks manually.
  • Better security. OAuth tokens are short-lived and refreshed automatically. A Private App token lives forever until you remember to rotate it.
  • Instant AI silence on agent claim. When a HubSpot agent assigns themselves to a conversation, the OpenCX AI stops replying within ~1 second instead of “on the next customer message”.

​
What changes

Legacy Private AppOAuth Public App
Setup time~15 min~30 sec
Access tokenPaste-and-storeIssued automatically, refreshed every ~30 min
Webhook URLManually copied into HubSpotSubscribed automatically on install
Workflow extensions in HubSpotNot available”Pause OpenCX AI”, “Resume OpenCX AI”, “Send to OpenCX AI”, “Request OpenCX handoff”
Owner-change AI silenceRace window of seconds-to-minutes< 1 second (P95)

​
How to migrate

  1. In OpenCX, open Settings → Integrations → HubSpot Service Hub.
  2. If you previously connected via a Private App, you’ll see a yellow banner at the top of the modal: “HubSpot Private Apps are being phased out — click Connect with HubSpot below to migrate.”
  3. Click the Connect with HubSpot button. A new browser tab opens HubSpot’s consent screen.
  4. Approve the requested scopes (these match what your Private App had: tickets, conversations.read/write, crm.objects.contacts.read/write, crm.objects.companies.read, crm.objects.deals.read, crm.objects.owners.read, automation).
  5. You’ll bounce back to OpenCX with a “HubSpot connected” toast. The integration card now shows Connected.
  6. Optional: in HubSpot, delete the OpenCX Private App you previously created. The new OAuth app supersedes it.
That’s it. Your existing tickets, conversations, and email signature settings stay intact during the switch — only the auth substrate changes underneath.

​
Frequently asked questions

​
Do I lose any tickets or conversation history during the switch?

No. The migration only touches the auth tokens. Your chat_sessions, chat_history, ticket links, and signature settings are untouched.

​
What if I have multiple HubSpot portals?

OpenCX currently supports one HubSpot portal per OpenCX organization. Reconnecting via OAuth will use the portal of whoever clicks Connect.

​
Can I roll back if something breaks?

Yes — for one release after migration, the legacy paste-token form remains available behind the Advanced — use a Private App access token accordion. After the OAuth-only flag flips on, the legacy path is hidden.

​
What happens to the workflow actions if I’m on legacy?

Workflow actions only work on the OAuth path. Until you migrate, Pause / Resume / Send-to-AI / Request handoff won’t appear inside HubSpot’s Workflow builder for your portal.