> ## 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.

# Intercom troubleshooting

> Debug Intercom connection, webhook, handoff, Assist Mode, and sync issues — 401 credential failures, duplicate messages, silent AI, missing handoffs.

Before debugging, have this ready:

* Your Intercom <Tooltip tip="The personal access token generated in Intercom's Developer Hub. Used to authenticate API calls between OpenCX and your Intercom workspace.">access token</Tooltip> and <Tooltip tip="Your Intercom workspace identifier, visible in your Intercom URL or app settings.">workspace ID</Tooltip>.
* A specific <Tooltip tip="OpenCX's identifier for a single conversation thread. Visible in the Inbox URL.">session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or Intercom conversation ID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Intercom.

<Tip>
  Re-run **Verify** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Intercom as your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** find the conversation in your [OpenCX Inbox](https://platform.open.cx/inbox) and check the session's AI reasoning, tool calls, and handoff event. That's far faster than inspecting webhooks or logs.
</Info>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Failed to verify credentials" on save**

<Tooltip tip="Usually caused by a revoked or expired token, a wrong workspace ID, or an Intercom plan without API access.">Likely cause</Tooltip>: token revoked, workspace ID wrong, or plan doesn't include API access.

**Fix:** regenerate the access token in Intercom's [Developer Hub](https://developers.intercom.com/). Confirm the workspace ID matches your Intercom URL. Confirm your Intercom plan includes API access.

### **Webhook not receiving events**

<Tooltip tip="The webhook URL was not pasted into Intercom, or the subscribed topics are incomplete. Without the webhook, OpenCX receives no conversation events.">Likely cause</Tooltip>: 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](https://platform.open.cx/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**

<Tooltip tip="The conversation may not be assigned to the AI admin, or Autopilot may be disabled for the channel. OpenCX only processes conversations assigned to the default admin.">Likely cause</Tooltip>: 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:

1. Confirm the conversation is assigned to the admin you selected as the default AI admin in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Intercom.
2. Confirm [Autopilot](https://platform.open.cx/settings/autopilot) is enabled for the channel (web or email).
3. 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.
4. Confirm the conversation was customer-initiated (outbound automations and bot messages are skipped).

### **Handoff creates a note but conversation stays assigned to AI**

<Tooltip tip="A race condition between the unassign request and a concurrent webhook event. The conversation may have been re-assigned before OpenCX finished the handoff.">Likely cause</Tooltip>: 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**

<Tooltip tip="The deduplication hash expired (1-hour TTL) or concurrent webhook deliveries arrived before the first was fully processed.">Likely cause</Tooltip>: 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**

<Warning>
  **Assist Mode is a discouraged fallback.** We recommend [autopilot](/handoff/introduction) for every new deployment — Assist exists only for teams that aren't yet ready to hand customer replies to the AI. If you're evaluating OpenCX, start with autopilot.
</Warning>

If you're already running Assist, <Tooltip tip="Assist only runs on conversations NOT assigned to the AI admin. If the conversation is assigned to the AI admin, it responds directly instead of posting an internal note.">likely cause</Tooltip>: conversation is assigned to the AI admin (Assist only runs on human-owned conversations), or Autopilot assist is disabled.

**Fix:** check these in order:

1. Confirm the conversation is assigned to a human agent, **not** the AI admin.
2. Confirm [Autopilot](https://platform.open.cx/settings/autopilot) assist is enabled for the channel.
3. Check if the topic is on the no-assist list in Autopilot settings.
4. The AI may have judged its own suggestion unhelpful and stayed quiet — check the session in [Inbox](https://platform.open.cx/inbox) for reasoning.

<AccordionGroup>
  <Accordion title="How to enable Assist (if you must)" icon="gear">
    Assist runs on the same webhook as direct AI replies — no extra credentials.

    1. Complete the [Intercom connection](/integrations/intercom/connect).
    2. In [Autopilot](https://platform.open.cx/settings/autopilot), enable assist per-channel (web or email).
    3. Assist only fires on conversations **not** assigned to the AI admin.

    Conversations Assist writes to are tagged `opencx_ai_assisted`. Drafts post as internal notes — the customer never sees them.
  </Accordion>
</AccordionGroup>

### **Custom attributes not appearing on session**

<Tooltip tip="The attribute may not be API-writable in Intercom, or the custom attribute delay is too low for your Intercom workflows to finish setting values.">Likely cause</Tooltip>: 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](/integrations/intercom/connect#settings-reference) (max 10 seconds).

### **Company data not syncing to contact**

<Tooltip tip="Company data sync is disabled by default. It must be explicitly enabled, and the contact must have at least one company attached in Intercom.">Likely cause</Tooltip>: sync disabled or contact has no company.

**Fix:** confirm **Company data sync** is set to "first company" or "all companies" in [settings](/integrations/intercom/connect#settings-reference). 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                |

<Note>
  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.
</Note>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect Intercom" icon="plug" href="/integrations/intercom/connect">
    Re-verify credentials and webhook setup.
  </Card>

  <Card title="Conversations" icon="messages" href="/integrations/intercom/conversations">
    How messages flow and how handoff works.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/intercom/channels/web">
    Per-channel details for Web and Email.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>