@capgo/capacitor-intercom

Intercom Capacitor plugin

Why Capacitor Intercom?

A fully re-implemented Intercom plugin for Capacitor 8, built to Capgo quality standards:

• Intercom iOS SDK 19+ - Latest Swift APIs with proper async handling
• Intercom Android SDK 17+ - Modern Intercom client integration
• Bug-free - Fixed known bugs from community implementations (e.g. hideInAppMessages on Android)
• Cross-platform - Consistent API across iOS and Android
• Full feature set - Messenger, Help Center, Articles, Carousels, Push, Identity Verification, and more

Essential for any app integrating Intercom for customer support, onboarding, or in-app messaging.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/intercom/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

npm install @capgo/capacitor-intercom
npx cap sync

Configuration

Add your Intercom keys to your Capacitor config:

{
  "plugins": {
    "CapgoIntercom": {
      "iosApiKey": "ios_sdk-xxx",
      "iosAppId": "yyy",
      "androidApiKey": "android_sdk-xxx",
      "androidAppId": "yyy"
    }
  }
}

Alternatively, you can initialize at runtime using loadWithKeys().

iOS

The Intercom iOS SDK (~> 19.0) is included automatically via CocoaPods or Swift Package Manager.

Push Notifications

1. Disable Intercom's auto push integration — Add this to your Info.plist to prevent conflicts with Capacitor's push handling:

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

2. Forward the device token to Capacitor — In your AppDelegate.swift:

import UIKit
import Capacitor

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Forward to Capacitor — the plugin's observer picks this up
        // and sends the token to Intercom automatically
        NotificationCenter.default.post(
            name: .capacitorDidRegisterForRemoteNotifications,
            object: deviceToken
        )
    }

    func application(_ application: UIApplication,
                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
        NotificationCenter.default.post(
            name: .capacitorDidFailToRegisterForRemoteNotifications,
            object: error
        )
    }
}

3. Register for push and handle notification taps — In your app's JavaScript:

import { PushNotifications } from '@capacitor/push-notifications';
import { CapgoIntercom as Intercom } from '@capgo/capacitor-intercom';

// Request permission + register
const perm = await PushNotifications.requestPermissions();
if (perm.receive === 'granted') {
  await PushNotifications.register();
}

// Auto-forward FCM token to Intercom
PushNotifications.addListener('registration', async (token) => {
  await Intercom.sendPushTokenToIntercom({ value: token.value });
});

// When user taps a notification, tell Intercom to open the conversation
PushNotifications.addListener('pushNotificationActionPerformed', async (action) => {
  const data = action.notification?.data;
  // iOS uses 'intercom_push_type', Android uses 'receiver'
  if (data?.intercom_push_type || data?.receiver === 'intercom_sdk') {
    await Intercom.receivePush(data);
  }
});

Note: The plugin automatically registers the APNs device token with Intercom when it detects .capacitorDidRegisterForRemoteNotifications. You must still upload your APNs Authentication Key (.p8) in the Firebase Console under Project Settings → Cloud Messaging → APNs Authentication Key.

Android

The Intercom Android SDK (17.4.2) is included automatically via Gradle.

Push Notifications

Since Android only allows one FirebaseMessagingService, this plugin does not register its own. Instead it provides IntercomFcmHelper — a static helper you call from your app's service.

1. Create your own FirebaseMessagingService in your app (e.g. app/src/main/java/.../MyFirebaseMessagingService.java):

package com.your.app;

import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;
import app.capgo.capacitor.intercom.IntercomFcmHelper;

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (IntercomFcmHelper.isIntercomPush(remoteMessage)) {
            IntercomFcmHelper.onMessageReceived(this, remoteMessage);
        } else {
            // Handle other push SDKs (e.g. @capacitor/push-notifications)
            // or your own notification logic here
        }
    }

    @Override
    public void onNewToken(String token) {
        IntercomFcmHelper.onNewToken(this, token);
        // Forward token to other SDKs if needed
    }
}

2. Register it in your app's AndroidManifest.xml:

<service
    android:name=".MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

This approach is compatible with any other Firebase plugin — you control the routing.

API

• loadWithKeys(...)
• registerIdentifiedUser(...)
• registerUnidentifiedUser()
• updateUser(...)
• logout()
• logEvent(...)
• displayMessenger()
• displayMessageComposer(...)
• displayHelpCenter()
• hideMessenger()
• displayLauncher()
• hideLauncher()
• displayInAppMessages()
• hideInAppMessages()
• displayCarousel(...)
• displayArticle(...)
• displaySurvey(...)
• setUserHash(...)
• setUserJwt(...)
• setBottomPadding(...)
• sendPushTokenToIntercom(...)
• receivePush(...)
• getUnreadConversationCount()
• addListener('windowDidShow', ...)
• addListener('windowDidHide', ...)
• addListener('unreadCountDidChange', ...)
• removeAllListeners()
• Interfaces

loadWithKeys(...)

loadWithKeys(options: IntercomLoadOptions) => Promise<void>

Initialize Intercom with API keys at runtime. Use this if you prefer not to configure keys in capacitor.config.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | IntercomLoadOptions |

registerIdentifiedUser(...)

registerIdentifiedUser(options: IntercomIdentifiedUserOptions) => Promise<void>

Register a known user with Intercom. At least one of userId or email must be provided.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | IntercomIdentifiedUserOptions |

registerUnidentifiedUser()

registerUnidentifiedUser() => Promise<void>

Register an anonymous user with Intercom.

updateUser(...)

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

Update user attributes in Intercom.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | IntercomUserUpdateOptions |

logout()

logout() => Promise<void>

Log the user out of Intercom.

logEvent(...)

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

Log a custom event in Intercom.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | IntercomLogEventOptions |

displayMessenger()

displayMessenger() => Promise<void>

Open the Intercom messenger.

displayMessageComposer(...)

displayMessageComposer(options: IntercomMessageComposerOptions) => Promise<void>

Open the message composer with a pre-filled message.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------- | | options | IntercomMessageComposerOptions |

displayHelpCenter()

displayHelpCenter() => Promise<void>

Open the Intercom help center.

hideMessenger()

hideMessenger() => Promise<void>

Hide the Intercom messenger.

displayLauncher()

displayLauncher() => Promise<void>

Show the Intercom launcher button.

hideLauncher()

hideLauncher() => Promise<void>

Hide the Intercom launcher button.

displayInAppMessages()

displayInAppMessages() => Promise<void>

Enable in-app messages from Intercom.

hideInAppMessages()

hideInAppMessages() => Promise<void>

Disable in-app messages from Intercom.

displayCarousel(...)

displayCarousel(options: IntercomCarouselOptions) => Promise<void>

Display a specific Intercom carousel.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | IntercomCarouselOptions |

displayArticle(...)

displayArticle(options: IntercomArticleOptions) => Promise<void>

Display a specific Intercom article.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | IntercomArticleOptions |

displaySurvey(...)

displaySurvey(options: IntercomSurveyOptions) => Promise<void>

Display a specific Intercom survey.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | IntercomSurveyOptions |

setUserHash(...)

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

Set the HMAC for identity verification.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | IntercomUserHashOptions |

setUserJwt(...)

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

Set JWT for secure messenger authentication.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | IntercomUserJwtOptions |

setBottomPadding(...)

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

Set the bottom padding for the Intercom messenger UI.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------- | | options | IntercomBottomPaddingOptions |

sendPushTokenToIntercom(...)

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

Send a push notification token to Intercom.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | IntercomPushTokenOptions |

receivePush(...)

receivePush(notification: IntercomPushNotificationData) => Promise<void>

Handle a received Intercom push notification.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------- | | notification | IntercomPushNotificationData |

getUnreadConversationCount()

getUnreadConversationCount() => Promise<IntercomUnreadCountResult>

Get the number of unread conversations for the current user.

Returns: Promise<IntercomUnreadCountResult>

addListener('windowDidShow', ...)

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

Listen for when the Intercom window is shown.

| Param | Type | | ------------------ | ---------------------------- | | eventName | 'windowDidShow' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

addListener('windowDidHide', ...)

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

Listen for when the Intercom window is hidden.

| Param | Type | | ------------------ | ---------------------------- | | eventName | 'windowDidHide' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

addListener('unreadCountDidChange', ...)

addListener(eventName: 'unreadCountDidChange', listenerFunc: (data: IntercomUnreadCountResult) => void) => Promise<PluginListenerHandle>

Listen for changes in the unread conversation count.

| Param | Type | | ------------------ | -------------------------------------------------------------------------------------------------- | | eventName | 'unreadCountDidChange' | | listenerFunc | (data: IntercomUnreadCountResult) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all event listeners.

Interfaces

IntercomLoadOptions

| Prop | Type | | ------------------- | ------------------- | | appId | string | | apiKeyIOS | string | | apiKeyAndroid | string |

IntercomIdentifiedUserOptions

| Prop | Type | | ------------ | ------------------- | | userId | string | | email | string |

IntercomUserUpdateOptions

| Prop | Type | | ---------------------- | ------------------------------------ | | userId | string | | email | string | | name | string | | phone | string | | languageOverride | string | | customAttributes | { [key: string]: any; } | | companies | IntercomCompany[] |

IntercomCompany

| Prop | Type | | ---------------------- | ------------------------------------ | | companyId | string | | name | string | | plan | string | | monthlySpend | number | | createdAt | number | | customAttributes | { [key: string]: any; } |

IntercomLogEventOptions

| Prop | Type | | ---------- | ------------------------------------ | | name | string | | data | { [key: string]: any; } |

IntercomMessageComposerOptions

| Prop | Type | | ------------- | ------------------- | | message | string |

IntercomCarouselOptions

| Prop | Type | | ---------------- | ------------------- | | carouselId | string |

IntercomArticleOptions

| Prop | Type | | --------------- | ------------------- | | articleId | string |

IntercomSurveyOptions

| Prop | Type | | -------------- | ------------------- | | surveyId | string |

IntercomUserHashOptions

| Prop | Type | | ---------- | ------------------- | | hmac | string |

IntercomUserJwtOptions

| Prop | Type | | --------- | ------------------- | | jwt | string |

IntercomBottomPaddingOptions

| Prop | Type | | ----------- | ------------------- | | value | number |

IntercomPushTokenOptions

| Prop | Type | | ----------- | ------------------- | | value | string |

IntercomPushNotificationData

IntercomUnreadCountResult

| Prop | Type | | ----------- | ------------------- | | count | number |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |