@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

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(options: IntercomLoadOptions) => Promise<void>

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

registerUnidentifiedUser() => Promise<void>

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

logout() => Promise<void>

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

displayMessenger() => Promise<void>

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

displayHelpCenter() => Promise<void>

hideMessenger() => Promise<void>

displayLauncher() => Promise<void>

hideLauncher() => Promise<void>

displayInAppMessages() => Promise<void>

hideInAppMessages() => Promise<void>

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

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

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

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

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

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

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

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

getUnreadConversationCount() => Promise<IntercomUnreadCountResult>

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

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

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

removeAllListeners() => Promise<void>