Capacitor Intercom plugin

@foodello/intercom

Capacitor plugin for enabling Intercom capabilities based on the Capacitor community plugin

Notice 🚀

This version is for Capacitor > v6. If you are looking for plugin for another Capacitor versions use:

• @foodello/intercom@^4.2.2 for v4
• @foodello/intercom@^5.0.0for v5

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>

Listen for when the unread conversation count is changed.

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

Returns: Promise<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

Intenseloop

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):

Stew 💻 📖	David Seek 💻	Roman Nikitin 💻	Anne Tomassoni 💻 👀	Maciej Modzelewski 💻	Oleg Yuzvik 🚧	Gustavo Corrêa Alves 📖
Jealvia 🚧	Adam Duren 💻 🚧	Rami Khafagi 💻	Masahiko Sakakibara 🚧	Dejardin Camille 💻	Mohamed Abdelgwad 🚧	Nathan 🚧

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