Skip to main content
OpenCX now uses the HubSpot OAuth Public App for new HubSpot connections. If your organization still uses a Private App access token, migrate from the HubSpot integration modal.

​
Why migrate

  • Private Apps are the legacy path. New features such as workflow extensions only work on OAuth.
  • 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. Private App tokens remain valid until rotated or revoked.
  • Faster agent takeover. HubSpot ownership changes can pause the AI without waiting for the next customer message.

​
What changes

​
How to migrate

  1. In OpenCX, open Settings → Integrations → HubSpot.
  2. Choose OAuth Public App. If your org is still on Private App auth, the modal shows an Action recommended banner.
  3. Click Connect with HubSpot. HubSpot opens its consent screen.
  4. Approve the requested permissions.
  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.
Your existing tickets, conversations, sessions, and email signature settings stay intact during the switch.

​
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?

Usually, yes. If your workspace still shows Private App (legacy), you can reconnect with the previous token path. Some organizations are OAuth-only, so the legacy form may be 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.

Connect HubSpot

OAuth setup and legacy fallback.

Handoff & Sync

Day-to-day ticket and conversation behavior.

Webhook Reference

Events OpenCX receives and writes back.

Troubleshooting

Reconnect prompts and sync issues.