HubSpot troubleshooting

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.

Before debugging, have this ready:

• Connection method — is HubSpot connected with OAuth Public App or Private App (legacy) in Settings → Integrations?
• Session ID — find it in the OpenCX inbox for the conversation in question.
• HubSpot conversation or ticket link — open the exact thread your rep is testing.

​

Common scenarios

​

OAuth connect or reconnect fails

Likely cause: wrong HubSpot portal, missing HubSpot admin access, canceled consent, or revoked app install. Fix:

1. In OpenCX, open Settings → Integrations → HubSpot.
2. Choose OAuth Public App and click Connect with HubSpot or Reconnect.
3. In HubSpot, confirm you are approving the correct portal.
4. If HubSpot blocks the install, ask a HubSpot super admin to approve connected apps for the portal.
5. If the redirect lands back on an error toast, retry once and share the error text with OpenCX support.

​

Private App token save fails

Likely cause: expired or revoked Private App token, wrong token format, or missing scopes. Fix:

1. Use OAuth if your workspace allows it; the Private App path is legacy.
2. If you must use legacy, confirm the token starts with pat-.
3. Confirm the Private App includes the scopes listed in Advanced: Private App (legacy).
4. Paste the token into Private App Access Token, enter the numeric Default User ID, and save.

​

Handoff runs but no ticket appears

Likely cause: the conversation didn’t originate from a channel HubSpot owns (most common), ticket creation is disabled, or the contact has no email for HubSpot to match. Fix:

1. Check the channel. Tickets appear automatically only when the conversation starts from a channel HubSpot owns — a HubSpot chat widget, or an email routed through a HubSpot inbox. Messages sent to OpenCX’s [email protected] address never reach HubSpot, so no ticket is created.
2. For non-HubSpot channels (OpenCX email, widget, WhatsApp, SMS, phone), use the create-hubspot-ticket-from-session workflow action on handoff.
3. Check with your OpenCX admin whether ticket creation is enabled for HubSpot.
4. Confirm the contact in the OpenCX session has an email address — HubSpot needs it to associate the ticket with a contact.
5. If all of the above are correct, check that the webhook is still registered in HubSpot (see below).

​

Rep replies don’t reach the customer

Likely cause: webhook not registered in HubSpot, wrong event subscriptions, uncommitted subscription changes, or stale webhook URL. Fix:

1. Confirm HubSpot still shows Connected via OAuth in OpenCX. Reconnect if the modal shows Reconnect required.
2. Confirm the rep replied publicly, not as an internal note. Internal notes sync to OpenCX as private agent comments and are not delivered to customers.
3. If you use the legacy Private App path, confirm the webhook subscriptions are committed in HubSpot and the target URL matches the URL shown in OpenCX.
4. Check the customer’s channel is still reachable (email valid, widget session open, phone number active).

​

AI stopped replying mid-thread

Likely cause: the conversation owner is not the configured AI user. Fix:

1. In HubSpot, open the conversation and check the Assigned to field.
2. Reassign to the user whose ID you configured as the Default User ID in OpenCX.
3. If you want the AI to keep drafting while reps own the conversation, enable Assist Mode instead.

​

Legacy webhook shows delivered in HubSpot but nothing happens

Likely cause: the webhook URL in HubSpot is stale or was copied from a different org. Fix:

1. In OpenCX, choose Private App (legacy) and re-copy the webhook URL.
2. In HubSpot, open your Legacy App (Settings → Integrations → Private Apps → Legacy Apps) → Webhooks and replace the target URL.
3. Trigger a test conversation to confirm events are now processed.

​

Email reaches HubSpot, threads appear, but no OpenCX session is created

Likely cause: the legacy Private App is missing the crm.objects.owners.read scope. How to confirm:

1. In HubSpot, open your Legacy App → Monitoring → API Calls.
2. Look for GET /crm/owners/v3/A-<number> returning 403 with MISSING_SCOPES in the error body. This is the exact failure.

Fix:

1. Legacy App → Scopes tab → enable crm.objects.owners.read, or migrate to OAuth.
2. Click Save / commit scope changes.
3. In OpenCX Settings → Integrations → HubSpot, re-save to refresh the cached client.
4. Send a fresh test email and confirm the session now appears in the OpenCX inbox.

​

CRM context panel is empty

Likely cause: CRM integration not connected, or the contact’s email doesn’t match any HubSpot record. Fix:

1. The CRM context panel is configured at Settings → CRMs — this is a separate connection from Settings → Integrations.
2. Confirm the contact’s email in OpenCX matches a contact in your HubSpot portal.
3. Test the CRM connection from Settings → CRMs.

​

Replies not syncing: full checklist

If handoff creates a ticket but replies do nothing:

1. Confirm the ticket has a handoff comment posted on the associated HubSpot conversation (AI summary, sentiment, language, OpenCX session link).
2. Confirm HubSpot is connected via OAuth, or re-check legacy webhook subscriptions if you are still on Private App auth.
3. Confirm the reply was sent as a public message, not an internal note.
4. Check the customer’s channel is still reachable (email valid, phone active, widget session open).
5. Confirm Autopilot or Assist Mode settings match the behavior you expect for that channel.

​

Limits & timing

---

​

Related Documentation