Name	Name	Last commit message	Last commit date
parent directory ..
android	android
example	example
ios	ios
src	src
.eslintignore	.eslintignore
.gitignore	.gitignore
.npmrc	.npmrc
.prettierrc.js	.prettierrc.js
.swiftlintrc.js	.swiftlintrc.js
BREAKING.md	BREAKING.md
CHANGELOG.md	CHANGELOG.md
CapawesomeCapacitorIntercom.podspec	CapawesomeCapacitorIntercom.podspec
LICENSE	LICENSE
Package.swift	Package.swift
README.md	README.md
package.json	package.json
rollup.config.mjs	rollup.config.mjs
tsconfig.json	tsconfig.json

Capacitor Intercom Plugin

Unofficial Capacitor plugin for Intercom.¹

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Features

The Capacitor Intercom plugin is a modern integration of the Intercom SDKs for Capacitor apps. Here are some of the key features:

🖥️ Cross-platform: Supports Android, iOS, and Web.
💬 Messenger: Present the Intercom Messenger and its Home, Messages, Help Center, and Tickets spaces.
👤 Identity: Log in identified or unidentified users with the modern login APIs, wired to the native result callbacks.
🔐 Identity Verification: Verify the user's identity with a user hash (HMAC) or a JSON Web Token (JWT).
🧩 User Attributes: Update the user's name, email, phone, custom attributes, and companies.
📚 Content: Present articles, carousels, surveys, conversations, and help center collections.
🔢 Unread Count: Read the unread conversation count and listen for changes.
🔔 Push Notifications: Compose cleanly with Firebase Cloud Messaging (Android) and APNs (iOS).
🌐 Typed Web SDK: Uses the official @intercom/messenger-js-sdk package on the web.
🤝 Compatibility: Looking for a different chat SDK? Check out the Crisp plugin.
📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The Intercom plugin is typically used wherever you want to offer live chat and customer support inside your app, for example:

Customer support: Let users chat with your support team directly from within the app.
User identification: Attach the signed-in user's identity and attributes to every conversation.
Self-service: Point users to articles, surveys, and help center collections without leaving the app.
Engagement: Track events and show the unread conversation count in your own UI.
Re-engagement: Notify users about new replies via push notifications.

Compatibility

Plugin Version	Capacitor Version	Status
0.x.x	>=8.x.x	Active support

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-intercom` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-intercom
npx cap sync

This plugin requires an Intercom account. You can find your App ID and the platform-specific API keys in the Intercom dashboard under Settings → Installation.

Android

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

$intercomSdkVersion version of io.intercom.android:intercom-sdk-base (default: 18.4.0)

This plugin depends on intercom-sdk-base (not the full intercom-sdk artifact) on purpose. The full artifact ships its own FirebaseMessagingService and automatically integrates Firebase Cloud Messaging, which conflicts with apps that manage push notifications themselves (e.g. via @capacitor-firebase/messaging). The base artifact leaves push handling to you (see below).

Push Notifications

Push notifications on Android are delivered through Firebase Cloud Messaging (FCM). Because this plugin uses the base SDK, you forward the push token and incoming messages to Intercom from your JavaScript code. This is what makes the plugin coexist cleanly with @capacitor-firebase/messaging:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';
import { Intercom } from '@capawesome/capacitor-intercom';

// Forward the FCM token to Intercom.
FirebaseMessaging.addListener('tokenReceived', async ({ token }) => {
  await Intercom.sendPushTokenToIntercom({ token });
});

// Forward incoming messages to Intercom.
FirebaseMessaging.addListener('notificationReceived', async ({ notification }) => {
  const data = notification.data ?? {};
  const { intercom } = await Intercom.isIntercomPushNotification({ data });
  if (intercom) {
    await Intercom.handlePushNotification({ data });
  }
});

iOS

The Intercom iOS SDK can be integrated via Swift Package Manager (recommended) or CocoaPods.

Info.plist

To manage push notifications yourself (and coexist with other push plugins), disable Intercom's automatic push integration by adding the following key to your ios/App/App/Info.plist file:

<key>IntercomAutoIntegratePushNotifications</key>
<false/>

Push Notifications

Push notifications on iOS are delivered through Apple Push Notification service (APNs):

Enable the Push Notifications capability for your app target in Xcode.
Register for remote notifications (e.g. via @capacitor-firebase/messaging or @capacitor/push-notifications).
Forward the APNs device token to Intercom as a hexadecimal string:

import { PushNotifications } from '@capacitor/push-notifications';
import { Intercom } from '@capawesome/capacitor-intercom';

PushNotifications.addListener('registration', async ({ value }) => {
  // `value` is the hexadecimal APNs device token on iOS.
  await Intercom.sendPushTokenToIntercom({ token: value });
});

You can then check and handle incoming notifications the same way as on Android using isIntercomPushNotification(...) and handlePushNotification(...).

Web

The web implementation loads the Intercom Messenger from Intercom's CDN at runtime. This requires an active network connection. If your app enforces a Content Security Policy (CSP), make sure to allow the Intercom domains (e.g. https://widget.intercom.io, https://js.intercomcdn.com, and wss://*.intercom.io).

Note

On the web, the Intercom launcher is visible by default after initialize(...), whereas on Android and iOS it is hidden until you present the Messenger. Use setLauncherVisible({ visible: false }) on the web if you want to match the mobile behavior.

Configuration

No configuration required for this plugin.

Usage

The following examples show how to use the plugin.

Initialize the plugin

Call initialize(...) once before all other methods:

import { Intercom } from '@capawesome/capacitor-intercom';

const initialize = async () => {
  await Intercom.initialize({
    appId: 'YOUR_APP_ID',
    androidApiKey: 'YOUR_ANDROID_API_KEY',
    iosApiKey: 'YOUR_IOS_API_KEY',
  });
};

Log in a user

import { Intercom } from '@capawesome/capacitor-intercom';

const loginUser = async () => {
  await Intercom.setUserHash({ userHash: 'YOUR_HMAC_HASH' });
  await Intercom.loginUser({
    userId: 'jane-doe',
    email: 'jane.doe@example.com',
  });
};

Update the user

Update the attributes of the current user:

import { Intercom } from '@capawesome/capacitor-intercom';

const updateUser = async () => {
  await Intercom.updateUser({
    name: 'Jane Doe',
    customAttributes: { plan: 'pro' },
    companies: [{ id: 'capawesome', name: 'Capawesome', plan: 'enterprise' }],
  });
};

Present the Messenger

Present the Intercom Messenger or a specific piece of content:

import { Intercom } from '@capawesome/capacitor-intercom';

const present = async () => {
  await Intercom.present({ space: 'home' });
};

const presentArticle = async () => {
  await Intercom.presentContent({ type: 'article', id: '123456' });
};

Listen for events

Listen for the unread conversation count:

import { Intercom } from '@capawesome/capacitor-intercom';

const addListeners = async () => {
  await Intercom.addListener('unreadConversationCountChange', ({ count }) => {
    console.log('Unread conversations:', count);
  });
};

API

getUnreadConversationCount()
handlePushNotification(...)
hide()
initialize(...)
isIntercomPushNotification(...)
logEvent(...)
loginUnidentifiedUser()
loginUser(...)
logout()
present(...)
presentContent(...)
presentMessageComposer(...)
sendPushTokenToIntercom(...)
setBottomPadding(...)
setInAppMessagesVisible(...)
setLauncherVisible(...)
setUserHash(...)
setUserJwt(...)
updateUser(...)
addListener('messengerHidden', ...)
addListener('messengerShown', ...)
addListener('unreadConversationCountChange', ...)
removeAllListeners()
Interfaces
Type Aliases

getUnreadConversationCount()

getUnreadConversationCount() => Promise<GetUnreadConversationCountResult>

Get the number of unread conversations for the current user.

Returns: Promise<GetUnreadConversationCountResult>

Since: 0.1.0

handlePushNotification(...)

handlePushNotification(options: HandlePushNotificationOptions) => Promise<void>

Handle an incoming push notification that belongs to Intercom.

Use isIntercomPushNotification(...) to check whether the notification belongs to Intercom before calling this method.

Only available on Android and iOS.

Param	Type
`options`	`HandlePushNotificationOptions`

Since: 0.1.0

hide()

hide() => Promise<void>

Hide any currently presented Intercom UI (e.g. the Messenger).

Since: 0.1.0

initialize(...)

initialize(options: InitializeOptions) => Promise<void>

Initialize the Intercom SDK with your app ID and API key.

This method must be called before any other method.

Param	Type
`options`	`InitializeOptions`

Since: 0.1.0

isIntercomPushNotification(...)

isIntercomPushNotification(options: IsIntercomPushNotificationOptions) => Promise<IsIntercomPushNotificationResult>

Check whether an incoming push notification belongs to Intercom.

Only available on Android and iOS.

Param	Type
`options`	`IsIntercomPushNotificationOptions`

Returns: Promise<IsIntercomPushNotificationResult>

Since: 0.1.0

logEvent(...)

logEvent(options: LogEventOptions) => Promise<void>

Log an event with an optional set of metadata.

Param	Type
`options`	`LogEventOptions`

Since: 0.1.0

loginUnidentifiedUser()

loginUnidentifiedUser() => Promise<void>

Since: 0.1.0

loginUser(...)

loginUser(options: LoginUserOptions) => Promise<void>

At least one of userId or email must be provided.

Param	Type
`options`	`LoginUserOptions`

Since: 0.1.0

logout()

logout() => Promise<void>

Log out the current user and clear the local Intercom data.

Since: 0.1.0

present(...)

present(options?: PresentOptions | undefined) => Promise<void>

Present the Intercom Messenger with the given space.

Param	Type
`options`	`PresentOptions`

Since: 0.1.0

presentContent(...)

presentContent(options: PresentContentOptions) => Promise<void>

Present a specific piece of Intercom content (e.g. an article, carousel, survey, or conversation).

Param	Type
`options`	`PresentContentOptions`

Since: 0.1.0

presentMessageComposer(...)

presentMessageComposer(options?: PresentMessageComposerOptions | undefined) => Promise<void>

Present the Intercom message composer, optionally pre-filled with an initial message.

Param	Type
`options`	`PresentMessageComposerOptions`

Since: 0.1.0

sendPushTokenToIntercom(...)

sendPushTokenToIntercom(options: SendPushTokenToIntercomOptions) => Promise<void>

Forward a push notification token to Intercom.

On Android, pass the Firebase Cloud Messaging (FCM) token. On iOS, pass the hexadecimal APNs device token.

Param	Type
`options`	`SendPushTokenToIntercomOptions`

Since: 0.1.0

setBottomPadding(...)

setBottomPadding(options: SetBottomPaddingOptions) => Promise<void>

Set the bottom padding of the Intercom UI (in-app messages and launcher).

Only available on Android and iOS.

Param	Type
`options`	`SetBottomPaddingOptions`

Since: 0.1.0

setInAppMessagesVisible(...)

setInAppMessagesVisible(options: SetInAppMessagesVisibleOptions) => Promise<void>

Set whether in-app messages are visible.

Param	Type
`options`	`SetInAppMessagesVisibleOptions`

Since: 0.1.0

setLauncherVisible(...)

setLauncherVisible(options: SetLauncherVisibleOptions) => Promise<void>

Set whether the Intercom launcher is visible.

Param	Type
`options`	`SetLauncherVisibleOptions`

Since: 0.1.0

setUserHash(...)

setUserHash(options: SetUserHashOptions) => Promise<void>

Set the user hash (HMAC) for identity verification.

This must be called before logging in the user.

Param	Type
`options`	`SetUserHashOptions`

Since: 0.1.0

setUserJwt(...)

setUserJwt(options: SetUserJwtOptions) => Promise<void>

Set the JSON Web Token (JWT) for identity verification.

This must be called before logging in the user.

Param	Type
`options`	`SetUserJwtOptions`

Since: 0.1.0

updateUser(...)

updateUser(options: UpdateUserOptions) => Promise<void>

Update the attributes of the current user.

Param	Type
`options`	`UpdateUserOptions`

Since: 0.1.0

addListener('messengerHidden', ...)

addListener(eventName: 'messengerHidden', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when the Intercom Messenger is hidden.

Only available on iOS and Web.

Param	Type
`eventName`	`'messengerHidden'`
`listenerFunc`	`() => void`

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('messengerShown', ...)

addListener(eventName: 'messengerShown', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when the Intercom Messenger is shown.

Only available on iOS and Web.

Param	Type
`eventName`	`'messengerShown'`
`listenerFunc`	`() => void`

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('unreadConversationCountChange', ...)

addListener(eventName: 'unreadConversationCountChange', listenerFunc: (event: UnreadConversationCountChangeEvent) => void) => Promise<PluginListenerHandle>

Called when the number of unread conversations changes.

Param	Type
`eventName`	`'unreadConversationCountChange'`
`listenerFunc`	`(event: UnreadConversationCountChangeEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

Interfaces

GetUnreadConversationCountResult

Prop	Type	Description	Since
`count`	`number`	The number of unread conversations.	0.1.0

HandlePushNotificationOptions

Prop	Type	Description	Since
`data`	`Record<string, unknown>`	The data of the push notification.	0.1.0

InitializeOptions

Prop	Type	Description	Since
`androidApiKey`	`string`	The Android API key of your Intercom app. Required to use the plugin on Android.	0.1.0
`appId`	`string`	The app ID of your Intercom app.	0.1.0
`iosApiKey`	`string`	The iOS API key of your Intercom app. Required to use the plugin on iOS.	0.1.0

IsIntercomPushNotificationResult

Prop	Type	Description	Since
`intercom`	`boolean`	Whether the push notification belongs to Intercom.	0.1.0

IsIntercomPushNotificationOptions

Prop	Type	Description	Since
`data`	`Record<string, unknown>`	The data of the push notification.	0.1.0

LogEventOptions

Prop	Type	Description	Since
`data`	`Record<string, string \| number \| boolean>`	The metadata of the event.	0.1.0
`name`	`string`	The name of the event.	0.1.0

LoginUserOptions

Prop	Type	Description	Since
`email`	`string`	The email address of the user.	0.1.0
`userId`	`string`	The unique identifier of the user.	0.1.0

PresentOptions

Prop	Type	Description	Default	Since
`space`	`IntercomSpace`	The space to present.	`'home'`	0.1.0

PresentContentOptions

Prop	Type	Description	Since
`id`	`string`	The identifier of the content to present. Required for the `article`, `carousel`, `survey`, and `conversation` content types.	0.1.0
`ids`	`string[]`	The identifiers of the content to present. Required for the `help-center-collections` content type.	0.1.0
`type`	`IntercomContentType`	The type of content to present.	0.1.0

PresentMessageComposerOptions

Prop	Type	Description	Since
`initialMessage`	`string`	The message to pre-fill the composer with.	0.1.0

SendPushTokenToIntercomOptions

Prop	Type	Description	Since
`token`	`string`	The push notification token. On Android, this is the Firebase Cloud Messaging (FCM) token. On iOS, this is the hexadecimal APNs device token.	0.1.0

SetBottomPaddingOptions

Prop	Type	Description	Since
`padding`	`number`	The bottom padding to set.	0.1.0

SetInAppMessagesVisibleOptions

Prop	Type	Description	Since
`visible`	`boolean`	Whether in-app messages should be visible.	0.1.0

SetLauncherVisibleOptions

Prop	Type	Description	Since
`visible`	`boolean`	Whether the launcher should be visible.	0.1.0

SetUserHashOptions

Prop	Type	Description	Since
`userHash`	`string`	The user hash (HMAC) for identity verification. The hash must be generated on your backend using your Intercom secret key. Never expose the secret key in your app.	0.1.0

SetUserJwtOptions

Prop	Type	Description	Since
`jwt`	`string`	The JSON Web Token (JWT) for identity verification. The token must be generated on your backend using your Intercom secret key. Never expose the secret key in your app.	0.1.0

UpdateUserOptions

Prop	Type	Description	Since
`companies`	`UpdateUserCompany[]`	The companies the user belongs to.	0.1.0
`customAttributes`	`Record<string, string \| number \| boolean>`	The custom attributes of the user.	0.1.0
`email`	`string`	The email address of the user.	0.1.0
`languageOverride`	`string`	The preferred language of the user as an ISO 639-1 code.	0.1.0
`name`	`string`	The name of the user.	0.1.0
`phone`	`string`	The phone number of the user.	0.1.0
`signedUpAt`	`number`	The date the user signed up as a Unix timestamp in seconds.	0.1.0
`unsubscribedFromEmails`	`boolean`	Whether the user is unsubscribed from emails.	0.1.0
`userId`	`string`	The unique identifier of the user.	0.1.0

UpdateUserCompany

Prop	Type	Description	Since
`createdAt`	`number`	The date the company was created as a Unix timestamp in seconds.	0.1.0
`customAttributes`	`Record<string, string \| number \| boolean>`	The custom attributes of the company.	0.1.0
`id`	`string`	The unique identifier of the company.	0.1.0
`monthlySpend`	`number`	The monthly spend of the company.	0.1.0
`name`	`string`	The name of the company.	0.1.0
`plan`	`string`	The plan of the company.	0.1.0

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

UnreadConversationCountChangeEvent

Prop	Type	Description	Since
`count`	`number`	The number of unread conversations.	0.1.0

Type Aliases

IntercomSpace

A space of the Intercom Messenger.

'home' | 'messages' | 'help-center' | 'tickets'

IntercomContentType

A type of Intercom content that can be presented.

'article' | 'carousel' | 'conversation' | 'help-center-collections' | 'survey'

Migration

If you are migrating from @capacitor-community/intercom or another Intercom plugin, note that this plugin uses the modern Intercom API names throughout. The deprecated register* login methods are intentionally not exposed. The following table maps common legacy method names to their modern equivalents:

Legacy method	This plugin
`registerIdentifiedUser`	`loginUser`
`registerUnidentifiedUser`	`loginUnidentifiedUser`
`logout`	`logout`
`displayMessenger`	`present`
`displayMessageComposer`	`presentMessageComposer`
`displayArticle`	`presentContent`
`displayCarousel`	`presentContent`
`displayHelpCenter`	`present({ space: 'help-center' })`
`hideMessenger`	`hide`
`unreadConversationCount`	`getUnreadConversationCount`
`setLauncherVisibility`	`setLauncherVisible`
`setInAppMessageVisibility`	`setInAppMessagesVisible`
`sendPushTokenToIntercom`	`sendPushTokenToIntercom`

Platform Support

Not every Intercom SDK feature is available on all platforms. The following table lists the notable per-platform differences of the plugin's API:

Method / Event	Android	iOS	Web
`handlePushNotification(...)`	✅	✅	❌
`isIntercomPushNotification(...)`	✅	✅	❌
`presentContent(...)` (`carousel`)	✅	✅	❌
`presentContent(...)` (`help-center-collections`)	✅	✅	❌
`sendPushTokenToIntercom(...)`	✅	✅	❌
`setBottomPadding(...)`	✅	✅	❌
`messengerShown` / `messengerHidden` events	❌	✅	✅

Additional notes:

On the web, getUnreadConversationCount(...) returns the last value received from the change event, since the web SDK exposes the count only through a callback.
The messengerShown and messengerHidden events are not available on Android because the Intercom Android SDK does not expose a window visibility hook.
setBottomPadding(...) uses pixels on Android and points on iOS, matching the respective native SDK.

Licensing

The Intercom Android and iOS SDKs are licensed under the Apache License 2.0 and are distributed via Maven Central, CocoaPods, and Swift Package Manager. The web SDK is licensed under the MIT license. This plugin only declares these SDKs as dependencies and does not bundle or modify them. Using the plugin requires an active Intercom account. The MIT license of this plugin covers the wrapper code only, not the Intercom SDKs.

FAQ

Do I need an Intercom account to use this plugin?

Yes. This plugin wraps the official Intercom SDKs, which require an active Intercom account, an app ID, and platform-specific API keys.

How is this plugin different from other similar plugins?

This plugin uses Intercom's modern login APIs (loginUnidentifiedUser(...) and loginUser(...)). On Android it depends on the base SDK, so it coexists cleanly with your own Firebase Cloud Messaging or APNs setup and lets you forward push notifications to Intercom yourself. It also ships a fully typed web implementation, cross-platform push notification helpers, and is backed by dedicated support.

Why does this plugin use `intercom-sdk-base` instead of `intercom-sdk` on Android?

The full intercom-sdk artifact automatically integrates Firebase Cloud Messaging by registering its own FirebaseMessagingService. This conflicts with apps that manage push notifications themselves (e.g. via @capacitor-firebase/messaging). The base artifact avoids this conflict and lets you forward push notifications to Intercom yourself.

How does identity verification work?

Generate a user hash (HMAC) or a JSON Web Token (JWT) on your backend using your Intercom secret key, then pass it via setUserHash(...) or setUserJwt(...) before logging in the user. Never expose your secret key in your app.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

Crisp: Unofficial Capacitor plugin for the Crisp live chat and customer support platform.
Formbricks: Unofficial Capacitor plugin for Formbricks to run in-app surveys.
PostHog: Unofficial Capacitor plugin for the PostHog product analytics platform.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

This project is not affiliated with, endorsed by, sponsored by, or approved by Intercom Inc. or any of its affiliates or subsidiaries. "Intercom" is a trademark of Intercom Inc. ↩

Uh oh!

Uh oh!

FilesExpand file tree

intercom

Directory actions

More options

Directory actions

More options

Latest commit

History

intercom

Folders and files

parent directory

README.md

Capacitor Intercom Plugin

Features

Use Cases

Compatibility

Installation

Android

Variables

Push Notifications

iOS

Info.plist

Push Notifications

Web

Configuration

Usage

Initialize the plugin

Log in a user

Update the user

Present the Messenger

Listen for events

API

getUnreadConversationCount()

handlePushNotification(...)

hide()

initialize(...)

isIntercomPushNotification(...)

logEvent(...)

loginUnidentifiedUser()

loginUser(...)

logout()

present(...)

presentContent(...)

presentMessageComposer(...)

sendPushTokenToIntercom(...)

setBottomPadding(...)

setInAppMessagesVisible(...)

setLauncherVisible(...)

setUserHash(...)

setUserJwt(...)

updateUser(...)

addListener('messengerHidden', ...)

addListener('messengerShown', ...)

addListener('unreadConversationCountChange', ...)

removeAllListeners()

Interfaces

GetUnreadConversationCountResult

HandlePushNotificationOptions

InitializeOptions

IsIntercomPushNotificationResult

IsIntercomPushNotificationOptions

LogEventOptions

LoginUserOptions

PresentOptions

PresentContentOptions

PresentMessageComposerOptions

SendPushTokenToIntercomOptions

SetBottomPaddingOptions

SetInAppMessagesVisibleOptions

SetLauncherVisibleOptions

SetUserHashOptions

SetUserJwtOptions

UpdateUserOptions

UpdateUserCompany

PluginListenerHandle

UnreadConversationCountChangeEvent

Type Aliases

IntercomSpace

Why does this plugin use `intercom-sdk-base` instead of `intercom-sdk` on Android?