Skip to main content
One-time setup to connect HubSpot to OpenCX. After this, conversations hand off as tickets and messages sync both ways.
Setup takes about 15 minutes. You need admin access in both HubSpot and OpenCX.

​
Before you start

The integration uses HubSpot’s conversations and ticketing APIs. Service Hub (Starter or above) is required.
You need permission to create Private Apps and manage webhook subscriptions in your HubSpot portal.
Only organization owners and admins can save integration credentials in the OpenCX dashboard.

​
Setup

1

Create a HubSpot Private App

In your HubSpot account, go to Settings → Integrations → Private Apps and create a new app. Name it something recognizable (e.g. “OpenCX”).Enable these scopes:
ScopePurpose
crm.schemas.contacts.readRead contact schema
crm.objects.contacts.readFetch contact data
crm.objects.companies.readFetch company data
crm.objects.deals.readFetch deal data
ticketsCreate and manage tickets
conversation.creationCreate conversations
conversation.deletionClean up conversations
conversation.newMessageReceive new messages
Save the app and copy the access token.
Copy the access token immediately — HubSpot shows it only once. The token starts with pat-na1-.
2

Open HubSpot settings in OpenCX

Go to Settings → Integrations in your OpenCX dashboard and find HubSpot.
3

Enter your credentials

Paste the access token and fill in the default user ID.
FieldValue
Access TokenThe pat-na1-... token from Step 1.
Default User IDFormat: A-12345. The HubSpot user ID conversations are assigned to when no routing rule applies. Find this in HubSpot under Settings → Users & Teams.
Click Save. OpenCX verifies the token and auto-detects your HubSpot portal.
4

Copy your webhook URL

After saving, OpenCX displays a webhook URL unique to your organization. Copy it — you’ll paste it in HubSpot next.
The webhook URL is signed and specific to your organization. Treat it like a password.
5

Register the webhook in HubSpot

In HubSpot, go to Settings → Integrations → Private Apps, open your app, and navigate to Webhooks.Subscribe to these events and paste your webhook URL as the target:
  • conversation.newMessage
  • conversation.messageCreated
  • ticket.propertyChange
6

Verify end to end

Start a conversation through one of your connected channels (web chat or email) and trigger a handoff. Confirm:
  1. A ticket appears in HubSpot tagged opencx_handedoff.
  2. The ticket has a conversation summary and transcript.
  3. Reply from HubSpot — confirm the reply reaches the customer.
If any step fails, check Troubleshooting for common causes.

​
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

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.

​
Disconnecting

To disconnect, click Disconnect in Settings → Integrations → HubSpot. Then remove the webhook subscription from your HubSpot Private App to stop event delivery.

Handoff & Sync

Ticket creation, contact sync, CRM context, assist mode.

Troubleshooting

Connection failures, missing tickets, reply sync issues.

HubSpot Overview

Capabilities, supported channels, observability.

Human Handoff

Global handoff settings and escalation rules.