Intercom

Intercom is a customer messaging platform combining live chat, helpdesk, product tours, and lifecycle email for support and engagement.

⚠️

This integration is currently in alpha. Configuration and behaviour may change.

Prerequisites

Complete these steps in Intercom before configuring Signal.

Access your Intercom workspace

Create an access token

Navigate to Settings > Developers > Developer Hub, then click New app. Once created:

Open the app’s Authentication tab.
Copy the Access Token — this is a personal/test token that does not expire.
For production, complete the Authorisation flow and use the OAuth access token (also long-lived).

Confirm your region

Workspace URL	Region	API Base
`app.intercom.com`	US	`https://api.intercom.io`
`app.eu.intercom.com`	EU	`https://api.eu.intercom.io`
`app.au.intercom.com`	AU	`https://api.au.intercom.io`

Configuration

Field	Type	Required	Description
`access_token`	secret	Yes	Intercom access token. Found in your developer app’s Authentication tab.
`region`	select	Yes	Intercom data region (`us`, `eu`, or `au`).

Signal Setup

Quick Setup

Navigate to Integrations in the sidebar.
Open the Integration Library tab.
Find Intercom under the Marketing Automation category.
Click Install, and fill in the required fields.
Click Install Integration.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/intercom/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Intercom",
    "variant": "default",
    "config": {
      "access_token": "dG9rOmxxxxxxxxxxxxxxxxxxxxxx",
      "region": "us"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

Datafly Event	Intercom Concept	Notes
`page`	Event via Events API	Sent as `page_viewed` event on the contact’s timeline.
`Product Viewed`	Event	Forwarded with product properties.
`Order Completed`	Event with revenue metadata	Mapped to an Intercom event with `value`, `currency` metadata.
`identify`	Contact create/update	Sent via `POST /contacts` or `PUT /contacts/{id}`.

The Intercom API version header is set to 2.11 by Signal.

Identity

Intercom contacts can be either users (role: user) or leads (role: lead). Signal forwards:

Field	Source	Notes
`external_id`	`user_id` from `datafly.identify()`	Your stable customer ID. Becomes Intercom’s `external_id` for user contacts.
`email`	`traits.email`	Primary identifier for unauthenticated leads.
`phone`	`traits.phone`	E.164 format.
`name`	`traits.name` or first+last	Display name in the inbox.

Call datafly.identify() once the user is authenticated:

datafly.identify("user-123", {
  email: "jane@example.com",
  name: "Jane Doe"
});

Intercom events should be sent under the functional consent category by default (Intercom is typically used for support, not pure marketing). For marketing-style outbound campaigns, use the marketing category.

Verify it’s working

Trigger a test event from your website.
In Intercom, navigate to Contacts and search for the test contact by email or external ID.
Click the contact and check the Events section for Signal-delivered custom events.
In Signal, check Live Events to confirm delivery with a 200 response status.

Troubleshooting

Symptom	Possible Cause	Resolution
`401 Unauthorized`	Invalid access token	Regenerate the token in Developer Hub > your app > Authentication.
`400 missing external_id or email`	No identifier on event	Intercom requires `external_id` (for users) or `email` (for leads). Ensure at least one is set.
Wrong region	US/EU/AU mismatch	Check your workspace URL and ensure the `region` config matches.
Event quota exceeded	Plan limit	Intercom enforces per-plan event limits. Reduce volume or upgrade the plan.

Visit Intercom API documentation for full reference.