# Intercom Destination Config Reference

Intercom is a customer messaging destination. RudderStack sends identify, track, and group events to Intercom’s REST API from its servers, or loads Intercom’s own SDKs in device mode — the Messenger on web, and the mobile SDKs on Android and iOS.

In an Intercom destination spec:

Sample configuration

yaml 
version: rudder/v1
kind: destination
metadata:
  name: intercom-prod
spec:
  id: intercom-prod
  display_name: Intercom Production
  type: intercom
  definition_version: 1
  enabled: true
  config:
    app_id: "{{ .INTERCOM_APP_ID }}"
    api_key: "{{ .INTERCOM_ACCESS_TOKEN }}"
    api_version: v2
    api_server: standard
    send_anonymous_id: true

    mobile_api_key_android: "{{ .INTERCOM_ANDROID_API_KEY }}"
    mobile_api_key_ios: "{{ .INTERCOM_IOS_API_KEY }}"

    event_filtering:
      blacklist:
        - Credit Card Added

    connection_mode:
      web: device
      android: device
      ios: device
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics

The above example loads Intercom’s SDKs on web, Android, and iOS in device mode, which use app_id and the mobile API keys, and sends server-side events in cloud mode with api_key — see Key dependencies.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Most Intercom keys affect only one connection mode, or one platform’s SDK, and each key says which. Rudder CLI accepts every key whatever the mode — a key for another mode is stored and ignored.

In cloud mode Intercom accepts identify, track, and group events. In device mode, web sources send identify, track, and page, and Android and iOS sources send identify and track.

Key dependencies

Device mode loads Intercom with app_id, and cloud mode calls Intercom’s API with api_key. Rudder CLI checks for each key twice — once on the destination, and once on each connection:

Key Destination check: required when Connection check: required when
app_id connection_mode is set, and every entry in it maps web, android, or ios to device A web, android, or ios source connects in device mode
api_key connection_mode is set, and every entry in it maps web, android, ios, unity, react_native, flutter, or cordova to cloud A source connects in cloud mode, except a cloud, android_kotlin, ios_swift, or warehouse source

A connection_mode that mixes modes, or that names cloud, android_kotlin, ios_swift, or warehouse, requires neither key at the destination check, and neither does a spec without connection_mode. A spec that misses a key the destination check requires fails validation. For the connection check, see Connect a source.

Set app_id if any source connects in device mode, and api_key if any source connects in cloud mode. Without api_key, RudderStack fails every cloud-mode event, whatever the source type — including the four source types Rudder CLI doesn’t check.

Android and iOS device mode also need the platform’s mobile API key, which Rudder CLI never requires — see Mobile device mode.

Connection

app_id

RequiredSecret

Type: string

Description: ID of your Intercom workspace, which Intercom’s web Messenger and mobile SDKs load with. The dashboard calls it App Id.

Notes:

  • Required when a web, android, or ios source connects in device mode — see Key dependencies. Leave it unset otherwise.
  • 1 to 100 characters, and must not contain line breaks.
  • A {{ path || fallback }} template is accepted in place of a literal.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

See Adding device mode integration.

api_key

RequiredSecret

Type: string

Description: Intercom access token RudderStack calls Intercom’s REST API with. The dashboard calls it Access Token.

Notes:

  • Required when a source connects in cloud mode — see Key dependencies. Leave it unset otherwise.
  • 1 to 100 characters, and must not contain line breaks.
  • A {{ path || fallback }} template is accepted in place of a literal.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

See Connection settings for where to find the access token.

Cloud mode

These keys configure how RudderStack calls Intercom’s API, so they apply only to events sent in cloud mode. The dashboard shows them only then.

api_version

Type: string

Default value: v2

Description: Intercom REST API version RudderStack sends to. The dashboard calls it Intercom REST API Version.

Notes:

  • v2 — the latest API version, 2.10.
  • v1 — API version 1.4, kept for backward compatibility.
See Intercom API v2.10 Migration Guide.

api_server

Type: string

Default value: standard

Description: Region of your Intercom workspace. The dashboard calls it API Server.

Notes:

  • One of standard (US), eu, or au.
  • Applies when api_version is v2. With v1, RudderStack always calls the US endpoint.
yaml 
api_version: v2
api_server: eu

send_anonymous_id

Type: boolean

Default value: false

Description: Send the event’s anonymousId as the Intercom user ID when userId is absent. The dashboard calls it Send AnonymousId as Secondary UserId.

Notes:

  • Without it, an identify or track event carrying neither a userId nor an email fails, because Intercom needs one of them.
See Configuration settings.

update_last_request_at

Type: boolean

Default value: true

Description: Set the user’s last seen time in Intercom to the time of each identify call. The dashboard calls it Enable this to update the last seen to the current time.

Notes:

  • Applies when api_version is v1. It has no effect with v2.
yaml 
api_version: v1
update_last_request_at: false

See Review connection settings in the migration guide.

Mobile device mode

These keys configure Intercom’s mobile SDKs. Each is a plain string, not keyed by source type, though it applies to one platform only.

Rudder CLI doesn’t require these keys, even when android or ios connects in device mode. Without the platform’s key, the SDK doesn’t initialize Intercom, so no device-mode events from that platform reach it.

mobile_api_key_android

Secret

Type: string

Description: Intercom API key for Android, from the Android installation settings in Intercom. The Android SDK initializes Intercom with it and app_id. The dashboard calls it Android API Key.

Notes:

  • Applies to android sources in device mode only.
  • At most 100 characters, and must not contain line breaks.
  • A {{ path || fallback }} template is accepted in place of a literal.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

See Configuration settings for where to find the key.

mobile_api_key_ios

Secret

Type: string

Description: Intercom API key for iOS, used on the same terms as mobile_api_key_android. The dashboard calls it iOS API Key.

Notes:

  • Applies to ios sources in device mode only.
  • At most 100 characters, and must not contain line breaks.
  • A {{ path || fallback }} template is accepted in place of a literal.
Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

Event filtering

Client-side event filtering applies only to sources connected in device mode — web, android, or ios. The dashboard shows these controls only then, and the SDK is what applies the filter.

Rudder CLI accepts the block in any mode, but events sent in cloud mode reach Intercom unfiltered.

event_filtering

Type: object

Description: Restricts which track events the SDK passes to Intercom, by event name.

Notes:

  • Applies to sources connected in device mode.
  • whitelist — array of event names to allow; every other track event is dropped.
  • blacklist — array of event names to drop; every other track event is allowed.
  • The two are mutually exclusive, and Rudder CLI enforces it — setting both fails validation.
  • Each name is at most 100 characters, or a {{ path || fallback }} template.
yaml 
connection_mode:
  web: device
event_filtering:
  blacklist:
    - Credit Card Added

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode

Type: object

Description: Maps each source type you connect to the mode its events reach Intercom in, using the modes in Source types.

Notes:

  • An entry is required for each source type you connect — see Connect a source.
  • A mode the source type doesn’t support on this destination fails validation — for example device for android_kotlin.
  • The entries also decide which credentials the destination needs — see Key dependencies.
yaml 
connection_mode:
  web: device
  ios: device
  cloud: cloud

Source types

Intercom accepts events from these source types in the mentioned connection modes:

Source type Connection mode
android cloud, device
android_kotlin cloud
ios cloud, device
ios_swift cloud
web cloud, device
unity cloud
react_native cloud
flutter cloud
cordova cloud
cloud cloud
warehouse cloud

web, android, and ios offer device mode, which loads Intercom’s own SDK in the browser or app. The Kotlin and Swift SDKs — android_kotlin and ios_swift — are cloud only. See Adding device mode integration and RudderStack Connection Modes.

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers Intercom to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify are invalid here.

Connect a source

An event stream connection to this destination is checked against three rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. Every type an event stream source can resolve to is supported here, so this check always passes.

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'intercom-prod' config has no 'connection_mode' entry for source type 'web'

The destination config must carry the credential for the connection’s mode. A web, android, or ios source connecting in device mode needs app_id. Without it:

destination 'intercom-prod' config is missing fields required to connect a 'web' source: app_id

A source connecting in cloud mode needs api_key. Without it:

destination 'intercom-prod' config is missing fields required to connect a 'web' source: api_key

cloud, android_kotlin, and ios_swift sources connect without either check. Set api_key for them anyway — see Key dependencies.

Secrets

api_key, app_id, mobile_api_key_android, and mobile_api_key_ios are the secret keys. Write each one you use as a {{ .VAR }} reference and supply the value at apply time:

yaml 
config:
  app_id: "{{ .INTERCOM_APP_ID }}"
  api_key: "{{ .INTERCOM_ACCESS_TOKEN }}"
  mobile_api_key_android: "{{ .INTERCOM_ANDROID_API_KEY }}"
  mobile_api_key_ios: "{{ .INTERCOM_IOS_API_KEY }}"
bash 
export RUDDER_INTERCOM_APP_ID="..."
export RUDDER_INTERCOM_ACCESS_TOKEN="..."
export RUDDER_INTERCOM_ANDROID_API_KEY="..."
export RUDDER_INTERCOM_IOS_API_KEY="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

See How to Use Variable Substitution in Rudder CLI.

Changes by release

No changes since this type became available.

For changes across every destination type, see Destination Type Changes by Release.

See more