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.

One-time setup to connect HubSpot to OpenCX. Use OAuth Public App unless your OpenCX admin tells you to use the legacy Private App path.
OAuth setup usually takes less than a minute. You need HubSpot admin access and OpenCX admin access.

​
Before you start

The integration uses HubSpot’s conversations and ticketing APIs. Service Hub (Starter or above) is required.
You need permission to approve connected apps for the HubSpot portal you want OpenCX to use.
Only organization owners and admins can save integration credentials in the OpenCX dashboard.

​
What OAuth handles for you

The OAuth Public App replaces the manual Private App setup:
OAuth Public App
ConnectionApprove OpenCX on HubSpot’s consent screen
TokensIssued and refreshed automatically
WebhooksRegistered by OpenCX during install
AI senderPicked from a HubSpot teammate dropdown after connect
Workflow actionsAdds OpenCX actions to HubSpot workflows

​
Setup

1

Open HubSpot integration settings

Open Settings → Integrations in your OpenCX dashboard and select HubSpot.The modal asks which connection method to use. Choose OAuth Public App.
If you already connected with a Private App, pick OAuth Public App to migrate. Existing tickets, sessions, and email signatures stay intact.
2

Connect with HubSpot

Click Connect with HubSpot. OpenCX redirects you to HubSpot’s consent screen.Choose the HubSpot portal to connect and approve the requested permissions.
The permissions cover conversations, tickets, contacts, companies, deals, owners, files, lists, and HubSpot workflow actions. OpenCX requests them through HubSpot’s standard app consent screen; you do not paste a token into OpenCX.
3

Confirm the connection in OpenCX

After approval, HubSpot redirects you back to Settings → Integrations. The HubSpot card shows Connected, and the modal shows Connected via OAuth.If the redirect shows an error, re-open the modal and try again. If HubSpot says the app is not available for the selected portal, confirm you are an admin for that portal.
4

Pick who the AI posts as

In the OAuth view, use AI posts as to select the HubSpot teammate OpenCX should attribute outgoing replies to.Customers see this teammate’s name on email replies. Use a dedicated AI teammate if your team wants replies to be clearly labeled.
5

Enable Autopilot for the channel

Before testing, enable Autopilot for the channel you’ll use in Settings → Autopilot.Autopilot is configured per channel. If it is off for Email, Web, SMS, WhatsApp, or Phone, OpenCX stores the conversation but does not auto-reply on that channel.
6

Send a test message

For a HubSpot conversation to appear automatically, the conversation must originate from a channel HubSpot owns — either a HubSpot chat widget or an email address routed through a HubSpot inbox.
  1. Send a test email to a HubSpot-connected inbox, or send a message through the HubSpot chat widget.
  2. Confirm the conversation appears in HubSpot.
  3. Confirm a matching session appears in the OpenCX inbox.
  4. Let the AI reply and confirm the reply posts back to the same HubSpot thread.
  5. Trigger a handoff and confirm the handoff note appears in HubSpot with a link back to the OpenCX session.
The test above is for HubSpot-owned channels. OpenCX-native channels can still create HubSpot tickets on handoff through the create-hubspot-ticket-from-session workflow action; use the channel pages for verification steps.

​
Workflow actions

OAuth installs add OpenCX actions to HubSpot workflows. Use them when HubSpot rules should control the AI:
ActionUse it when
Pause OpenCX AIA HubSpot workflow claims the conversation for a human.
Resume OpenCX AIA workflow returns a handed-off conversation to the AI.
Send to OpenCX AIA workflow decides the latest customer message should be processed by the AI.
Request OpenCX handoffHubSpot should ask OpenCX to hand the session to a human.
Workflow actions are available only on the OAuth Public App path. They do not appear for legacy Private App connections.

​
Email signatures

Append branded email signatures to outgoing replies sent through HubSpot. Signatures are matched to the sender’s email domain, so different domains can have different signatures.
1

Open HubSpot settings

Go to Settings → Integrations → HubSpot in your OpenCX dashboard.
2

Add a signature

In the OAuth view, scroll to Email Signatures and click Add. Enter the domain pattern and paste your signature HTML.
3

Add more domains (optional)

Repeat for each domain that needs a different signature.

​
Domain matching

PatternMatches
open.cxEmails from open.cx only (exact match)
*.nlAll emails ending with .nl (wildcard)
*.co.ukAll emails ending with .co.uk (wildcard)
Exact domain matches always take priority over wildcard patterns. If you have both open.cx and *.cx, emails from open.cx use the exact-match signature.

​
Advanced: Private App (legacy)

Use Private App (legacy) only when OAuth is unavailable for your organization or support asks you to use the fallback path.
In HubSpot, go to Settings → Integrations → Private Apps → Legacy Apps → Create Legacy App and choose Private.Enable these scopes: crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.companies.read, crm.objects.deals.read, crm.objects.owners.read, tickets, conversations.read, and conversations.write.Copy the Private App Access Token after creation. HubSpot shows it only once.
In OpenCX, choose Private App (legacy) and copy the Webhook URL.In HubSpot, paste that URL into the Private App’s Webhooks tab, set event throttling high enough for your volume, and subscribe to:
Object typeEvent
ConversationNew message
ConversationConversation creation
TicketProperty change
Click Commit changes in HubSpot after editing subscriptions.
In OpenCX, enter:
FieldValue
Private App Access TokenThe pat-... token from HubSpot.
Default User IDThe numeric HubSpot user ID only, with no A- prefix.
Find the user ID in HubSpot under Settings → Users & Teams. Open the teammate profile and copy the number at the end of the URL.

​
Disconnecting

To disconnect an OAuth install, click Disconnect in Settings → Integrations → HubSpot, then type DELETE to confirm. Existing OpenCX sessions remain available. If you use the legacy Private App path, also remove the webhook subscriptions from your HubSpot Legacy App.

Handoff & Sync

Ticket creation, contact sync, CRM context.

Troubleshooting

Connection failures, missing tickets, reply sync issues.

HubSpot Overview

Capabilities, supported channels, observability.

Human Handoff

Global handoff settings and escalation rules.