Notice 🚀

This version is for Capacitor > v5. If you are looking for plugin for Capacitor v4 please use @foodello/intercom@^4.2.2.

Thanks for the all the authors with their work in @capacitor-community/intercom. We have noticed that the repository was left behind the newest updates and the original repository did not get updates quick enough once pull request were opened. So we decided to serve the newest Intercom capabilities under seperate org until the original repository catches the changes.

This plugin is built for the Capacitor v4 upwards.

Installation

Using npm:

npm install @foodello/intercom

Using yarn:

yarn add @foodello/intercom

Sync native files:

npx cap sync
```¨

## Usage

Import Intercom plugin into your project.

```js
import { Capacitor } from '@capacitor/core';
import { Intercom } from '@foodello/intercom';
import { PushNotifications } from '@capacitor/push-notifications';

Initialize Intercom plugin.

/**
 * Web requires loading and initializing the script of the SDK
 * with the Intercom web config defined in IntercomWebConfig Interface.
 * 
 * Only available in Web.
 * @since 4.2.0
 */
if (!Capacitor.isNativePlatform()) {
  await Intercom.load({ app_id: 'xxx' });
}

// Android and iOS does not require seperate initialization

API

• load(...)
• loadWithKeys(...)
• registerIdentifiedUser(...)
• loginIdentifiedUser(...)
• registerUnidentifiedUser()
• loginUnidentifiedUser()
• updateUser(...)
• logout()
• logEvent(...)
• displayMessenger()
• displayMessageComposer(...)
• displayHelpCenter()
• hideMessenger()
• displayLauncher()
• hideLauncher()
• displayInAppMessages()
• hideInAppMessages()
• displayCarousel(...)
• setUserHash(...)
• setBottomPadding(...)
• sendPushTokenToIntercom(...)
• receivePush(...)
• displayArticle(...)
• presentContent(...)
• present(...)
• setupUnreadConversationListener()
• removeUnreadConversationListener()
• getUnreadConversationCount()
• addListener(...)
• Interfaces
• Enums

IntercomPlugin Interface

load(...)

load(config: IntercomWebConfig) => Promise<void>

Load Intercom and set configs on Web environment.

Only available for Web

| Param | Type | | ------------ | --------------------------------------------------------------- | | config | IntercomWebConfig |

loadWithKeys(...)

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

Load Intercom and set configs on Web environment.

Only available for iOS and Android

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | LoadWithKeysOption |

registerIdentifiedUser(...)

registerIdentifiedUser(options: { userId?: string; email?: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------- | | options | { userId?: string; email?: string; } |

loginIdentifiedUser(...)

loginIdentifiedUser(options: { userId?: string; email?: string; }) => Promise<void>

Login an identified user with Intercom.

| Param | Type | | ------------- | ------------------------------------------------- | | options | { userId?: string; email?: string; } |

registerUnidentifiedUser()

registerUnidentifiedUser() => Promise<void>

loginUnidentifiedUser()

loginUnidentifiedUser() => Promise<void>

Login an unidentified user with Intercom.

updateUser(...)

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

Updates a user's attributes in Intercom.

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

logout()

logout() => Promise<void>

Logs the user out of Intercom.

logEvent(...)

logEvent(options: { name: string; data?: any; }) => Promise<void>

Logs an event with optional metadata in Intercom.

| Param | Type | | ------------- | ------------------------------------------ | | options | { name: string; data?: any; } |

displayMessenger()

displayMessenger() => Promise<void>

displayMessageComposer(...)

displayMessageComposer(options: { message: string; }) => Promise<void>

Displays the Intercom Message Composer with an initial message.

| Param | Type | | ------------- | --------------------------------- | | options | { message: string; } |

displayHelpCenter()

displayHelpCenter() => Promise<void>

hideMessenger()

hideMessenger() => Promise<void>

Hides the Intercom Messenger.

displayLauncher()

displayLauncher() => Promise<void>

Displays the default Intercom Launcher.

hideLauncher()

hideLauncher() => Promise<void>

Hides the Intercom Launcher.

displayInAppMessages()

displayInAppMessages() => Promise<void>

Displays Intercom In-App Messages.

hideInAppMessages()

hideInAppMessages() => Promise<void>

Hides Intercom In-App Messages.

displayCarousel(...)

displayCarousel(options: { carouselId: string; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------ | | options | { carouselId: string; } |

setUserHash(...)

setUserHash(options: { hmac: string; }) => Promise<void>

Sets the HMAC user hash for Intercom Identity Verification.

| Param | Type | | ------------- | ------------------------------ | | options | { hmac: string; } |

setBottomPadding(...)

setBottomPadding(options: { value: string; }) => Promise<void>

Sets the bottom padding for the Intercom Messenger.

| Param | Type | | ------------- | ------------------------------- | | options | { value: string; } |

sendPushTokenToIntercom(...)

sendPushTokenToIntercom(options: { value: string; }) => Promise<void>

Sends a push token to Intercom.

| Param | Type | | ------------- | ------------------------------- | | options | { value: string; } |

receivePush(...)

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

Processes a received Intercom push notification.

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

displayArticle(...)

displayArticle(options: { articleId: string; }) => Promise<void>

| Param | Type | | ------------- | ----------------------------------- | | options | { articleId: string; } |

presentContent(...)

presentContent(options: { contentType: IntercomContent; contentId: string; }) => Promise<void>

Presents an Intercom content item by its type and ID.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------ | | options | { contentType: IntercomContent; contentId: string; } |

present(...)

present(options: { space: IntercomSpace; }) => Promise<void>

Presents the Intercom's space.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | { space: IntercomSpace; } |

setupUnreadConversationListener()

setupUnreadConversationListener() => Promise<void>

Setup listener for unread conversation count updates.

removeUnreadConversationListener()

removeUnreadConversationListener() => Promise<void>

Remove listener for unread conversation count updates.

getUnreadConversationCount()

getUnreadConversationCount() => Promise<{ unreadCount: number; }>

Get current unread conversation count.

Returns: Promise<{ unreadCount: number; }>

addListener(...)

addListener(eventName: 'updateUnreadCount', listenerFunc: (data: { unreadCount: number; }) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for when the unread conversation count is changed.

| Param | Type | | ------------------ | -------------------------------------------------------- | | eventName | "updateUnreadCount" | | listenerFunc | (data: { unreadCount: number; }) => void |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Interfaces

IntercomWebConfig

IntercomWebConfig Interface

Represent configs that are available on Intercom Web SDK.

| Prop | Type | Description | | ------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | app_id | string | Configure Intercom Web APP ID. The APP ID of your Intercom app which will indicate where to store any data. Only available for Web | | api_base | IntercomRegionalApiBase | Configure Intercom's regional API baseurl. For customers who are using Regional Data Hosting for Intercom, there is an additional parameter to set, to ensure your Messenger is pointing to your Regional workspace. Only available for Web | | custom_launcher_selector | string | Configure Intercom custom launcher selector. The CSS selector of an element to trigger Intercom("show") in order to activate the messenger. To target an element by ID: "#id_of_element". To target elements by class ".classname_of_elements" Only available for Web | | alignment | IntercomAlignment | Configure Intercom default launcher alignment. Dictate the alignment of the default launcher icon to be on the left/right. Possible values: "left" or "right" (any other value is treated as right). Only available for Web | | vertical_padding | number | Configure Intercom default launcher icon's vertical padding. Move the default launcher icon vertically. Padding from bottom of screen. Minimum value: 20. Does not work on mobile. Only available for Web | | horizontal_padding | number | Configure Intercom default launcher icon's horizontal padding. Move the default launcher icon horizontally. Padding from right side of screen Minimum value: 20. Does not work on mobile. Only available for Web | | hide_default_launcher | boolean | Configure Intercom default launcher icon's visibility. Hide the default launcher icon. Setting to false will forcefully show the launcher icon. Only available for Web | | session_duration | number | Configure Intercom session duration. Time in milliseconds for the Intercom session to be considered active. A value of 5 * 60 * 1000 would set the expiry time to be 5 minutes Only available for Web | | action_color | string | Configure action color for Intercom. Used in button links and more to highlight and emphasise. The color string can be any valid CSS Color Name HEX or RGB Only available for Web | | background_color | string | Configure background color for Intercom. Used behind your team profile and other attributes. The color string can be any valid CSS Color Name HEX or RGB Only available for Web |

LoadWithKeysOption

LoadWithKeysOption Interface.

Represents options required for dynamic load of native Intercom SDK.

Only available for iOS and Android.

| Prop | Type | Description | | ------------------- | ------------------- | -------------------- | | appId | string | | | iosApiKey | string | Required for iOS | | androidApiKey | string | Required for Android |

IntercomUserUpdateOptions

IntercomUserUpdateOptions Interface

Represents the options for updating a user's attributes in Intercom.

Only available for iOS and Android.

| Prop | Type | | ---------------------- | ------------------------------------------------------- | | userId | string | | email | string | | name | string | | phone | string | | languageOverride | string | | customAttributes | Record<string, any> | | company | CompanyOption | | companies | CompanyOption[] |

CompanyOption

CompanyOption Interface.

Represents Intercom option to include company details.

| Prop | Type | Description | | ---------------------- | -------------------------------------- | ----------------------------- | | name | string | Required for Web | | companyId | string | Required for Native platforms | | createdAt | number | Unix timestamp | | monthlySpend | number | | | plan | string | | | customAttributes | Record<string, any> | |

IntercomPushNotificationData

IntercomPushNotificationData Interface

Represents the structure of a received Intercom push notification.

Only available for iOS and Android.

| Prop | Type | | ------------------------------- | ------------------- | | conversation_id | string | | message | string | | body | string | | author_name | string | | image_url | string | | app_name | string | | receiver | string | | conversation_part_type | string | | intercom_push_type | string | | uri | string | | push_only_conversation_id | string | | instance_id | string | | title | string | | priority | number |

PluginListenerHandle

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

Enums

IntercomRegionalApiBase

| Members | Value | | -------- | --------------------------------------------- | | Us | 'https://api-iam.intercom.io' | | Eu | 'https://api-iam.eu.intercom.io' | | Au | 'https://api-iam.au.intercom.io' |

IntercomAlignment

| Members | Value | | ----------- | -------------------- | | Left | 'left' | | Right | 'right' |

IntercomContent

| Members | Value | Description | | --------------- | ------------------------ | ---------------------------------- | | Article | 'article' | | | Survey | 'survey' | | | Carousel | 'carousel' | Only available for iOS and Android | | Checklist | 'checklist' | Only available for Web | | News | 'news' | Only available for Web | | Tour | 'tour' | Only available for Web |

IntercomSpace

| Members | Value | Description | | ---------------- | ----------------------- | ---------------------- | | Home | 'home' | | | Messages | 'messages' | | | HelpCenter | 'help' | | | News | 'news' | Only available on web. | | Tasks | 'tasks' | Only available on web. |

Configurations

iOS setup

• ionic start my-cap-app --capacitor
• cd my-cap-app
• npm install —-save @foodello/intercom
• mkdir www && touch www/index.html
• npx cap add ios
• add intercom keys to capacitor's configuration file

{
 …
  "plugins": {
   "Intercom": {
      "iosApiKey": "ios_sdk-xxx",
      "iosAppId": "yyy"
    }
  }
…
}

• npx cap open ios
• sign your app at xcode (general tab)

Tip: every time you change a native code you may need to clean up the cache (Product > Clean build folder) and then run the app again.

Android setup

• ionic start my-cap-app --capacitor
• cd my-cap-app
• npm install —-save @foodello/intercom
• mkdir www && touch www/index.html
• npx cap add android
• add intercom keys to capacitor's configuration file

{
 …
  "plugins": {
   "Intercom": {
      "androidApiKey": "android_sdk-xxx",
      "androidAppId": "yyy"
    }
  }
…
}

• npx cap open android

Now you should be set to go. Try to run your client using ionic cap run android --livereload.

Tip: every time you change a native code you may need to clean up the cache (Build > Clean Project | Build > Rebuild Project) and then run the app again.

License

MIT

Original repository's maintainers and sponsors

This repository is based on the wonderful work of the official @capacitor-community/intercom -plugin. Here we want to acknowledge the mastermind and sponsors behind that work.

Sponsors

Maintainers

| Maintainer | GitHub | Social | | ------------ | --------------------------------------- | ----------------------------------------- | | Stewan Silva | stewones | @stewones |

Future plans

If you have any ideas what we should include, please open a new issue for it.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!