- Your Intercom and .
- A specific (from Inbox) or Intercom conversation ID where the problem shows.
- The webhook URL shown in Settings → Integrations → Intercom.
Fastest path to root cause: find the conversation in your OpenCX Inbox and check the session’s AI reasoning, tool calls, and handoff event. That’s far faster than inspecting webhooks or logs.
Common scenarios
Jump to the symptom that matches what you’re seeing.”Failed to verify credentials” on save
: token revoked, workspace ID wrong, or plan doesn’t include API access. Fix: regenerate the access token in Intercom’s Developer Hub. Confirm the workspace ID matches your Intercom URL. Confirm your Intercom plan includes API access.Webhook not receiving events
: webhook URL not configured in Intercom, or wrong event subscriptions. Fix: open your Intercom app in the Developer Hub and confirm the webhook URL matches the one shown in Settings → Integrations → Intercom. Confirm you’re subscribed to all five required topics:conversation.user.created, conversation.user.replied, conversation.admin.replied, conversation.admin.assigned, conversation.admin.closed.
AI not responding to conversations
: conversation not assigned to AI admin, Autopilot disabled, or Process on assignment is enabled but the conversation hasn’t been assigned yet. Fix: check these in order:- Confirm the conversation is assigned to the admin you selected as the default AI admin in Settings → Integrations → Intercom.
- Confirm Autopilot is enabled for the channel (web or email).
- If Process on assignment is enabled, the AI waits for an explicit assignment event — check that your Intercom routing rules assign new conversations to the AI admin.
- Confirm the conversation was customer-initiated (outbound automations and bot messages are skipped).
Handoff creates a note but conversation stays assigned to AI
: concurrent webhook events re-assigned the conversation before the handoff completed. Fix: this is a transient timing issue. OpenCX uses a lock to prevent race conditions, but rapid concurrent events can occasionally conflict. If this happens consistently, open a support request with the session ID.Duplicate AI replies on the same message
: dedup window expired or concurrent webhook retries. Fix: OpenCX deduplicates messages by content hash with a 1-hour window. If Intercom retries a webhook delivery after the window expires, a duplicate can occur. This is rare — if it happens consistently, confirm your Intercom webhook is not configured to retry aggressively.Assist Mode not posting suggestions
: conversation is assigned to the AI admin (Assist only runs on human-owned conversations), or Autopilot assist is disabled. Fix: check these in order:- Confirm the conversation is assigned to a human agent, not the AI admin.
- Confirm Autopilot assist is enabled for the channel.
- Check if the topic is on the no-assist list in Autopilot settings.
- The AI may have judged its own suggestion unhelpful and stayed quiet — check the session in Inbox for reasoning.
Custom attributes not appearing on session
: attribute not API-writable, or delay too short. Fix: in Intercom, confirm the custom attribute is marked as API-writable. If your Intercom workflows set attributes after conversation creation, increase the custom attribute delay in settings (max 10 seconds).Company data not syncing to contact
: sync disabled or contact has no company. Fix: confirm Company data sync is set to “first company” or “all companies” in settings. Confirm the Intercom contact has at least one company attached.Limits & timing
| Value | |
|---|---|
| Initial webhook wait (web) | ~4 seconds |
| Initial webhook wait (email) | ~30 seconds |
| Message deduplication window | 1 hour |
| Session creation lock timeout | 3 seconds |
| Conversation unassign lock | 500 ms |
| Custom attribute delay | 0–10 seconds (configurable) |
| Resolution note delay | ~15 seconds |
OpenCX retries on transient Intercom API failures but does not indefinitely retry. If your Intercom workspace is rate-limited or experiencing downtime, some webhook events may be missed. Check your Intercom Developer Hub webhook activity log for failed deliveries.
Related Documentation
Connect Intercom
Re-verify credentials and webhook setup.
Conversations
How messages flow and how handoff works.
Channels
Per-channel details for Web and Email.
Handoff settings
Global handoff rules and office hours.