Skip to content

Latest commit

 

History

History
730 lines (473 loc) · 21 KB

README.md

File metadata and controls

730 lines (473 loc) · 21 KB

@capgo/capacitor-intercom

Capgo - Instant updates for capacitor

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/>
  1. 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
        )
    }
}
  1. 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
    }
}
  1. 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(...)

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>