Connect Intercom

Generate an access token, copy your workspace and teammate IDs, enter credentials, configure the webhook, and choose how handoffs are routed.

One-time setup: enter your Intercom credentials, pick the teammate the AI replies as, paste the webhook URL into Intercom, and choose how handoffs are routed.

This page covers the shared Intercom connection. Once connected, see the Web or Email channel pages for per-channel verification steps.

Before you start

Intercom workspace with API access

You need an Intercom workspace on a plan that includes API access. You also need admin-level permissions to generate access tokens in the Developer Hub.

Admin access in OpenCX

Only organization admins can connect integrations. Confirm your role at Settings → Organization.

A dedicated Intercom teammate for the AI

Designate or create a teammate that represents the AI (for example, “AI Assistant”). Customers see this teammate as the author of every AI reply, so a dedicated bot account is strongly preferred over a real teammate’s account. You’ll copy this teammate’s ID in step 3.

Setup

1. Generate an access token

   In Intercom, go to Settings → Integrations → Developer Hub. Create a new app if you don’t already have one, or open an existing app.

   Inside the app, open Authentication and copy the Access token displayed beneath the app name. You can return to this page at any time to view the token again.

   Treat this access token like a password. It grants full read and write access to your Intercom conversations and contacts — don’t share it, don’t paste it into shared channels or tickets, and rotate it immediately if you suspect it has leaked.

2. Copy your workspace ID

   In Intercom, go to Settings → Workspace → General and copy the App ID field. Intercom uses “App ID” and “Workspace ID” interchangeably — they refer to the same value.

3. Copy your AI teammate ID

   Use the dedicated teammate from the prerequisites (create one first if you haven’t).

   In Intercom, go to Settings → Workspace → Teammates and click the teammate. The teammate ID appears as the last segment of the URL on the profile page:

   app.intercom.com/a/apps/<WORKSPACE_ID>/admins/<TEAMMATE_ID>
   

   Copy <TEAMMATE_ID> — that’s the value you’ll paste into the AI Admin ID field in OpenCX.

   Every AI-generated reply is posted as this teammate. Use a dedicated bot account (for example, “AI Assistant”) rather than a real teammate to avoid confusion with your team’s own replies.

4. Enter credentials in OpenCX

   Open Settings → Integrations in your OpenCX dashboard and select Intercom. OpenCX generates a webhook URL the moment the modal opens — you’ll use it in the next step.

   Fill in:

   Field	Value
   Access token	The token from step 1.
   Workspace ID	The App ID from step 2.
   AI Admin ID	The teammate ID from step 3.

   Click Save. OpenCX validates the credentials by listing your Intercom conversations. If validation fails, double-check that the token has not been revoked and that your Intercom plan includes API access.

5. Configure the webhook

   Still in the OpenCX modal, copy the Webhook URL.

   In Intercom, go to Settings → Integrations → Developer Hub → choose your app → Webhooks and paste the URL. See Intercom’s webhook setup guide for reference.

   Subscribe to these topics:

   • conversation.user.created
   • conversation.user.replied
   • conversation.admin.replied
   • conversation.admin.assigned
   • conversation.admin.open.assigned
   • conversation.admin.closed

   Without the webhook, OpenCX cannot receive conversation events and the AI will not respond to any messages. If you later change the app or rotate the token, re-verify that the webhook is still pointing at the OpenCX URL.

6. Configure handoff assignment

   Choose what happens when the AI hands off a conversation:

   • Unassigned (default) — removes the AI teammate and leaves the conversation in your triage queue for any teammate to pick up.
   • Specific teammate — assigns to a named teammate on handoff.
   • Specific team — assigns to an Intercom team on handoff.
   • Team and teammate — assigns to both a team and a specific teammate simultaneously.
7. Enable full conversation sync (optional)

   Open the Sync Settings tab inside the Intercom modal and toggle Full Conversation Auto Sync to sync every conversation in your Intercom workspace — not only the ones assigned to the AI teammate.

   Non-AI conversations are stored for reporting, insights, and supervision, and are not billed as AI interactions. With this on, the AI can also be brought into a conversation partway through by assigning it to the AI teammate.

8. Send a test message

   Open your Intercom Messenger and send a test message. The AI should reply within a few seconds. Then say “I want to talk to a human” — you should see an internal handoff note appear, and the conversation should be unassigned (or reassigned per your handoff configuration).

   For channel-specific verification, see Web or Email.

Settings reference

All settings are configured at Settings → Integrations → Intercom, across the Connection, Handoff Settings, and Sync Settings tabs.

Setting	Purpose
Default teammate (AI Admin ID)	The Intercom teammate the AI replies as. Required.
Default team	Fallback team for routing. Optional.
Handoff assignment	Where conversations go on handoff: unassigned, specific teammate, specific team, or both team and teammate.
Ignore first message	Skip AI processing on the opening message. Useful when Intercom bots handle the greeting.
Process on assignment	Wait for the conversation to be assigned to the AI teammate before processing, instead of processing on the first message.
Full conversation sync	Configured in the Sync Settings tab. Stores every Intercom conversation in OpenCX — not just those assigned to the AI — for reporting and supervision.
Forward unsupported attachments	Pass PDF, video, and audio attachments to the AI as placeholder text so it can acknowledge them.
Send citations as note	Post an internal note linking to the AI’s source citations in OpenCX after each reply.
Company data sync	Sync custom attributes from the contact’s Intercom company to their OpenCX profile. Options: disabled, first company only, all companies.
Custom attribute delay	Seconds to wait before re-fetching conversation custom attributes after creation. Handles Intercom race conditions where attributes are set by workflows after the conversation is created. Max 10 seconds.

Disconnecting

To remove the Intercom integration, open Settings → Integrations → Intercom and click Disconnect. This deletes stored credentials and stops webhook processing. Existing OpenCX sessions are preserved but no longer receive updates from Intercom.

---

Related Documentation

Conversations

How messages flow, handoff steps, and tags.

Channels

Per-channel implementation details for Web and Email.

Troubleshooting

Credentials failing, webhook silent, AI not replying.