Skip to content

Integrating Intercom

Auth: OAuth 2.0 · Partner program: required · Setup time: about 25 minutes · Last verified: 2026-05-23

Intercom is a messaging-first customer-support and engagement platform. The adapter wraps the Intercom REST API and exposes conversations, contacts, companies, admins, and tags into the canonical customer-support schema.

  • OAuth 2.0 Authorization Code grant. Authorize at https://app.intercom.com/oauth. Exchange via POST to https://api.intercom.io/auth/eagle/token.
  • Access tokens are long-lived bearer tokens; Intercom does not currently rotate them on a fixed schedule. Use the /me endpoint to validate and re-prompt the user if it 401s.
  1. An Intercom workspace at intercom.com.
  2. A registered app in the Developer Hub (developers.intercom.com). On the Authentication page, tick Use OAuth and supply at least one HTTPS redirect URL.
  3. To distribute the app to other Intercom customers, the app must be submitted for review and listed on the Intercom App Store. Internal apps used only by your own workspace can skip review.
  1. Open /platforms in the admin UI, filter to Customer Support, click Intercom.
  2. Fill Configure:
    • clientId — from your Intercom app’s Basic Information page.
    • clientSecret — from your Intercom app’s Basic Information page.
    • redirectUri — ${PUBLIC_BASE_URL}/auth/customer-support/intercom/callback.
  3. Enable the adapter.

Intercom scopes are declared on the Authentication page and granted at install. Common selections for the canonical schema:

  • Read and list users and companies, Write users and companies
  • Read conversations, Write conversations
  • Read admins
  • Read tags, Write tags
  • Read tickets, Write tickets
  • Read events, Write events

Over-scoping is the most common reason apps are rejected in the marketplace review — request only what the integration needs.

Configure webhooks under your app’s Webhooks page. Intercom signs each delivery with HMAC-SHA1 using your app’s Client Secret as the key; the signature arrives in the X-Hub-Signature header as sha1=<hex>.

Verify against the raw request body byte-for-byte — re-serialising JSON changes the digest. Subscribe to conversation.*, contact.*, company.*, and ticket.* topics.

  • Marketplace review for production distribution. Internal apps run without review; public distribution requires Intercom App Store approval. Plan for revisions if you ask for write scopes beyond your stated use case.
  • X-Hub-Signature is SHA-1. Many platforms use SHA-256 — Intercom does not.
  • Regional hosts exist (api.eu.intercom.io, api.au.intercom.io). Read app.region from the token response; the adapter routes requests accordingly.
  • JWT signing of body affects verification. When porting verification code, use the exact raw body — Python’s json.dumps(...) re-serialisation breaks signature comparison.