@capawesome/capacitor-crisp

v0.1.0

Published

21 days ago

Unofficial Capacitor plugin for Crisp on Android, iOS, and Web.

0High
0Medium
0Low

robingenz

capacitor plugin native capacitor-plugin crisp chat live chat customer support helpdesk messaging

Capacitor Crisp Plugin

Unofficial Capacitor plugin for Crisp.[^1]

Features

The Capacitor Crisp plugin is a comprehensive integration of the Crisp chat SDKs for Capacitor apps. Here are some of the key features:

🖥️ Cross-platform: Supports Android, iOS, and Web.
💬 Chatbox: Open the Crisp chatbox with a single method call.
👤 User Identity: Set the user's email, nickname, phone number, avatar, and company.
🔐 Identity Verification: Verify the user's identity with an HMAC-SHA256 email signature.
🧩 Session Data: Attach custom data, segments, and events to the session.
📚 Helpdesk: Open the helpdesk search or a specific helpdesk article.
🔔 Push Notifications: Interoperate with Firebase Cloud Messaging (Android) and APNs (iOS).
📡 Typed Events: Listen for chat, message, and session events with typed listeners.
🌐 Typed Web SDK: Uses the official crisp-sdk-web package on the web.
📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The Crisp plugin is typically used wherever you want to offer live chat and customer support inside your app, for example:

Customer support: Let users chat with your support team directly from within the app.
User identification: Attach the signed-in user's email, name, and company to every conversation.
Self-service: Point users to helpdesk articles without leaving the app.
Contextual data: Enrich conversations with session data, segments, and events based on user behavior.
Re-engagement: Notify users about new operator replies via push notifications.

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | >=8.x.x | Active support |

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-crisp` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-crisp
npx cap sync

This plugin requires a Crisp account. You can find your Website ID in the Crisp dashboard under Settings → Website Settings → Setup & Integrations.

Android

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

$crispSdkVersion version of im.crisp:crisp-sdk (default: 2.0.22)
$firebaseMessagingVersion version of com.google.firebase:firebase-messaging (default: 24.1.1)

Minimum SDK Version

The Crisp Android SDK requires a minimum SDK version of 24. Make sure the minSdkVersion in your app's variables.gradle file is set to 24 or higher.

Multidex

The Crisp Android SDK requires multidex to be enabled. Enable it in your app's android/app/build.gradle file:

android {
  defaultConfig {
    multiDexEnabled true
  }
}

FileProvider

The Crisp Android SDK ships its own FileProvider (used for chat attachments) with the authority ${applicationId}.im.crisp.client.uploadfileprovider. This authority is merged automatically and does not conflict with your app's own FileProvider, so no additional configuration is required.

Push Notifications

Push notifications on Android are delivered through Firebase Cloud Messaging (FCM). There are two ways to integrate them:

Option A — Crisp's own notification service (zero-config)

If your app does not use its own FirebaseMessagingService, add the following service to the application tag of your android/app/src/main/AndroidManifest.xml file:

<service
  android:name="im.crisp.client.external.notification.CrispNotificationService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

Option B — Share an existing FirebaseMessagingService

If your app already receives push notifications (e.g. via @capacitor-firebase/messaging), forward incoming messages to Crisp from your JavaScript code:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';
import { Crisp } from '@capawesome/capacitor-crisp';

FirebaseMessaging.addListener('notificationReceived', async ({ notification }) => {
  const data = notification.data ?? {};
  const { crisp } = await Crisp.isCrispPushNotification({ data });
  if (crisp) {
    await Crisp.handlePushNotification({ data });
  }
});

You can enable or disable Crisp push notifications at runtime with setNotificationsEnabled(...).

iOS

The Crisp iOS SDK can be integrated via Swift Package Manager (recommended) or CocoaPods.

[!NOTE] Crisp will stop publishing new CocoaPods releases in September 2026. We recommend using Swift Package Manager. If your app still uses CocoaPods, plan to migrate to Swift Package Manager before then.

Info.plist

The Crisp chatbox lets users send image and file attachments. Add the following keys to your ios/App/App/Info.plist file so users can attach photos:

<key>NSCameraUsageDescription</key>
<string>The app needs access to your camera to send photos in the chat.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>The app needs access to your photo library to send photos in the chat.</string>

Push Notifications

Push notifications on iOS are delivered through Apple Push Notification service (APNs):

Enable the Push Notifications capability for your app target in Xcode.
Register for remote notifications (e.g. via @capacitor-firebase/messaging or @capacitor/push-notifications).

The plugin automatically forwards the APNs device token to Crisp once your app has registered for remote notifications, so no additional token handling is required.

Use setShouldPromptForNotificationPermission(...) to control whether the Crisp SDK prompts the user for the notification permission.

Web

The web implementation loads the Crisp chatbox from Crisp's CDN at runtime. This requires an active network connection. If your app enforces a Content Security Policy (CSP), make sure to allow the Crisp domains (e.g. client.crisp.chat, *.crisp.chat, and wss://*.relay.crisp.chat).

Configuration

No configuration required for this plugin.

Usage

The following examples show how to use the plugin.

Configure the plugin

Call configure(...) once before all other methods:

import { Crisp } from '@capawesome/capacitor-crisp';

const configure = async () => {
  await Crisp.configure({
    websiteId: 'YOUR_WEBSITE_ID',
  });
};

Open the chat

Open the Crisp chatbox:

import { Crisp } from '@capawesome/capacitor-crisp';

const openChat = async () => {
  await Crisp.openChat();
};

Set the user

Set the information of the current user, optionally with identity verification:

import { Crisp } from '@capawesome/capacitor-crisp';

const setUser = async () => {
  await Crisp.setUser({
    email: '[email protected]',
    emailSignature: 'YOUR_HMAC_SIGNATURE',
    nickname: 'Jane Doe',
  });
};

Attach session data

Attach custom data, segments, and events to the current session:

import { Crisp, SessionEventColor } from '@capawesome/capacitor-crisp';

const attachSessionData = async () => {
  await Crisp.setSessionString({ key: 'plan', value: 'pro' });
  await Crisp.setSessionSegment({ segment: 'checkout' });
  await Crisp.pushSessionEvent({ name: 'purchase', color: SessionEventColor.Green });
};

Listen for events

Listen for chat, message, and session events:

import { Crisp } from '@capawesome/capacitor-crisp';

const addListeners = async () => {
  await Crisp.addListener('sessionLoaded', ({ sessionId }) => {
    console.log('Session loaded:', sessionId);
  });
  await Crisp.addListener('messageReceived', ({ content }) => {
    console.log('Message received:', content);
  });
};

API

configure(...)

configure(options: ConfigureOptions) => Promise<void>

Configure the plugin with your Crisp website ID.

This method must be called before any other method.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | ConfigureOptions |

Since: 0.1.0

handlePushNotification(...)

handlePushNotification(options: HandlePushNotificationOptions) => Promise<void>

Handle an incoming push notification that belongs to Crisp.

Use isCrispPushNotification(...) to check whether the notification belongs to Crisp before calling this method.

Only available on Android.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | HandlePushNotificationOptions |

Since: 0.1.0

isCrispPushNotification(...)

isCrispPushNotification(options: IsCrispPushNotificationOptions) => Promise<IsCrispPushNotificationResult>

Check whether an incoming push notification belongs to Crisp.

Only available on Android.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------- | | options | IsCrispPushNotificationOptions |

Returns: Promise<IsCrispPushNotificationResult>

Since: 0.1.0

openChat()

openChat() => Promise<void>

Open the chat.

Since: 0.1.0

openHelpdeskArticle(...)

openHelpdeskArticle(options: OpenHelpdeskArticleOptions) => Promise<void>

Open a specific helpdesk article.

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | OpenHelpdeskArticleOptions |

Since: 0.1.0

pushSessionEvent(...)

pushSessionEvent(options: PushSessionEventOptions) => Promise<void>

Push a session event to the current session.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | PushSessionEventOptions |

Since: 0.1.0

resetSession()

resetSession() => Promise<void>

Reset the current session.

This clears the current session and starts a new one on the next interaction.

Since: 0.1.0

searchHelpdesk()

searchHelpdesk() => Promise<void>

Open the helpdesk with the search view.

Since: 0.1.0

setCompany(...)

setCompany(options: SetCompanyOptions) => Promise<void>

Set the company of the current user.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | SetCompanyOptions |

Since: 0.1.0

setNotificationsEnabled(...)

setNotificationsEnabled(options: SetNotificationsEnabledOptions) => Promise<void>

Enable or disable push notifications.

Only available on Android.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------- | | options | SetNotificationsEnabledOptions |

Since: 0.1.0

setSessionBool(...)

setSessionBool(options: SetSessionBoolOptions) => Promise<void>

Set a boolean value for the given key in the current session.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | SetSessionBoolOptions |

Since: 0.1.0

setSessionInt(...)

setSessionInt(options: SetSessionIntOptions) => Promise<void>

Set an integer value for the given key in the current session.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | SetSessionIntOptions |

Since: 0.1.0

setSessionSegment(...)

setSessionSegment(options: SetSessionSegmentOptions) => Promise<void>

Set the segment of the current session.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | SetSessionSegmentOptions |

Since: 0.1.0

setSessionString(...)

setSessionString(options: SetSessionStringOptions) => Promise<void>

Set a string value for the given key in the current session.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | SetSessionStringOptions |

Since: 0.1.0

setShouldPromptForNotificationPermission(...)

setShouldPromptForNotificationPermission(options: SetShouldPromptForNotificationPermissionOptions) => Promise<void>

Set whether the user should be prompted for the notification permission.

Only available on iOS.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------------------------------------- | | options | SetShouldPromptForNotificationPermissionOptions |

Since: 0.1.0

setTokenId(...)

setTokenId(options: SetTokenIdOptions) => Promise<void>

Set the token ID of the current user.

The token ID is used to restore a session across devices and logins. You may also set it directly via configure(...).

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | SetTokenIdOptions |

Since: 0.1.0

setUser(...)

setUser(options: SetUserOptions) => Promise<void>

Set the information of the current user.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | SetUserOptions |

Since: 0.1.0

addListener('chatClosed', ...)

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

Called when the chat is closed.

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

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('chatOpened', ...)

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

Called when the chat is opened.

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

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('messageReceived', ...)

addListener(eventName: 'messageReceived', listenerFunc: (event: MessageReceivedEvent) => void) => Promise<PluginListenerHandle>

Called when a message is received from the operator.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------- | | eventName | 'messageReceived' | | listenerFunc | (event: MessageReceivedEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('messageSent', ...)

addListener(eventName: 'messageSent', listenerFunc: (event: MessageSentEvent) => void) => Promise<PluginListenerHandle>

Called when a message is sent by the user.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------- | | eventName | 'messageSent' | | listenerFunc | (event: MessageSentEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('sessionLoaded', ...)

addListener(eventName: 'sessionLoaded', listenerFunc: (event: SessionLoadedEvent) => void) => Promise<PluginListenerHandle>

Called when the session is loaded.

This is also the recommended way to get the session ID.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------- | | eventName | 'sessionLoaded' | | listenerFunc | (event: SessionLoadedEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

Interfaces

ConfigureOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ------------------------------------- | ----- | | tokenId | string | The token ID of the current user. | 0.1.0 | | websiteId | string | The website ID of your Crisp website. | 0.1.0 |

HandlePushNotificationOptions

| Prop | Type | Description | Since | | ---------- | ------------------------------------------ | ---------------------------------- | ----- | | data | Record<string, unknown> | The data of the push notification. | 0.1.0 |

IsCrispPushNotificationResult

| Prop | Type | Description | Since | | ----------- | -------------------- | ----------------------------------------------- | ----- | | crisp | boolean | Whether the push notification belongs to Crisp. | 0.1.0 |

IsCrispPushNotificationOptions

OpenHelpdeskArticleOptions

| Prop | Type | Description | Since | | -------------- | ------------------- | ----------------------------- | ----- | | category | string | The category of the article. | 0.1.0 | | id | string | The ID (slug) of the article. | 0.1.0 | | locale | string | The locale of the article. | 0.1.0 | | title | string | The title of the article. | 0.1.0 |

PushSessionEventOptions

| Prop | Type | Description | Default | Since | | ----------- | --------------------------------------------------------------- | ----------------------- | ----------------------------------- | ----- | | color | SessionEventColor | The color of the event. | SessionEventColor.Blue | 0.1.0 | | name | string | The name of the event. | | 0.1.0 |

SetCompanyOptions

| Prop | Type | Description | Since | | ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ | ----- | | description | string | The description of the company. | 0.1.0 | | employment | SetCompanyEmployment | The employment information of the user at the company. | 0.1.0 | | geolocation | SetCompanyGeolocation | The geolocation of the company. | 0.1.0 | | name | string | The name of the company. | 0.1.0 | | url | string | The URL of the company. | 0.1.0 |

SetCompanyEmployment

| Prop | Type | Description | Since | | ----------- | ------------------- | ----------------------------------------- | ----- | | role | string | The role of the user at the company. | 0.1.0 | | title | string | The job title of the user at the company. | 0.1.0 |

SetCompanyGeolocation

| Prop | Type | Description | Since | | ------------- | ------------------- | --------------------------- | ----- | | city | string | The city of the company. | 0.1.0 | | country | string | The country of the company. | 0.1.0 |

SetNotificationsEnabledOptions

| Prop | Type | Description | Since | | ------------- | -------------------- | --------------------------------------------- | ----- | | enabled | boolean | Whether push notifications should be enabled. | 0.1.0 |

SetSessionBoolOptions

| Prop | Type | Description | Since | | ----------- | -------------------- | ------------------------------ | ----- | | key | string | The key of the session data. | 0.1.0 | | value | boolean | The value of the session data. | 0.1.0 |

SetSessionIntOptions

| Prop | Type | Description | Since | | ----------- | ------------------- | ------------------------------ | ----- | | key | string | The key of the session data. | 0.1.0 | | value | number | The value of the session data. | 0.1.0 |

SetSessionSegmentOptions

| Prop | Type | Description | Since | | ------------- | ------------------- | --------------------------- | ----- | | segment | string | The segment of the session. | 0.1.0 |

SetSessionStringOptions

SetShouldPromptForNotificationPermissionOptions

| Prop | Type | Description | Since | | ------------- | -------------------- | -------------------------------------------------------------------- | ----- | | enabled | boolean | Whether the user should be prompted for the notification permission. | 0.1.0 |

SetTokenIdOptions

| Prop | Type | Description | Since | | ------------- | ------------------- | --------------------------------- | ----- | | tokenId | string | The token ID of the current user. | 0.1.0 |

SetUserOptions

| Prop | Type | Description | Since | | -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | avatarUrl | string | The URL of the user's avatar. | 0.1.0 | | email | string | The email address of the user. | 0.1.0 | | emailSignature | string | The HMAC-SHA256 signature of the user's email address for identity verification. The signature must be generated on your backend using your Crisp secret key. Never expose the secret key in your app. | 0.1.0 | | nickname | string | The nickname of the user. | 0.1.0 | | phone | string | The phone number of the user. | 0.1.0 |

PluginListenerHandle

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

MessageReceivedEvent

| Prop | Type | Description | Since | | ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----- | | content | string | null | The text content of the message. This is null if the message has no text content (e.g. a file or audio message). | 0.1.0 |

MessageSentEvent

SessionLoadedEvent

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------------- | ----- | | sessionId | string | The ID of the loaded session. | 0.1.0 |

Enums

SessionEventColor

| Members | Value | Since | | ------------ | --------------------- | ----- | | Black | 'BLACK' | 0.1.0 | | Blue | 'BLUE' | 0.1.0 | | Brown | 'BROWN' | 0.1.0 | | Green | 'GREEN' | 0.1.0 | | Grey | 'GREY' | 0.1.0 | | Orange | 'ORANGE' | 0.1.0 | | Pink | 'PINK' | 0.1.0 | | Purple | 'PURPLE' | 0.1.0 | | Red | 'RED' | 0.1.0 | | Yellow | 'YELLOW' | 0.1.0 |

Platform Support

Not every Crisp SDK feature is available on all platforms. The following table lists the per-platform differences of the plugin's API:

| Method | Android | iOS | Web | | -------------------------------------------- | :-----: | :-: | :-: | | setSessionBool(...) | ✅ | ✅ | ✅ | | isCrispPushNotification(...) | ✅ | ❌ | ❌ | | handlePushNotification(...) | ✅ | ❌ | ❌ | | setNotificationsEnabled(...) | ✅ | ❌ | ❌ | | setShouldPromptForNotificationPermission(...) | ❌ | ✅ | ❌ |

On iOS, the Crisp SDK detects and handles its own push notifications internally once the APNs device token has been forwarded, so the JavaScript isCrispPushNotification(...) and handlePushNotification(...) methods are not available there.

The following features of the Crisp SDKs are intentionally not part of this plugin's initial release: unread message count, bot scenarios, runtime locale override, and audio/video calls. Open an issue if you need any of them.

Licensing

The Crisp Android and iOS SDKs are proprietary, closed-source binaries provided by Crisp IM SAS. This plugin only declares them as dependencies (via Maven, CocoaPods, and Swift Package Manager) and does not bundle or modify them. Using the plugin requires an active Crisp account and website ID. The MIT license of this plugin covers the wrapper code only, not the Crisp SDKs.

FAQ

Do I need a Crisp account to use this plugin?

Yes. This plugin wraps the official Crisp SDKs, which require an active Crisp account and a website ID.

How is this plugin different from other similar plugins?

This plugin exposes the Crisp SDKs through a fully typed API, including a strongly typed listener for each event and dedicated helpdesk methods. Identity verification is built in through email-signature HMAC, and push notifications are handled entirely through Crisp's public API. It ships a typed web implementation alongside Android and iOS, supports Swift Package Manager ahead of the CocoaPods sunset, and stays unopinionated by never forcing an automatic show or hide of the chatbox. It is actively maintained and backed by dedicated support.

How do I get the session ID?

Listen for the sessionLoaded event. The event payload contains the sessionId. There is no synchronous getter, because the session is loaded asynchronously.

How does identity verification work?

Generate an HMAC-SHA256 signature of the user's email address on your backend using your Crisp secret key, then pass it as the emailSignature option of setUser(...). Never expose your secret key in your app.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Crisp IM SAS or any of its affiliates or subsidiaries. "Crisp" is a trademark of Crisp IM SAS.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Capacitor Crisp Plugin

Features

Use Cases

Compatibility

Installation

Android

Variables

Minimum SDK Version

Multidex

FileProvider

Push Notifications

iOS

Info.plist

Push Notifications

Web

Configuration

Usage

Configure the plugin

Open the chat

Set the user

Attach session data

Listen for events

API

configure(...)

handlePushNotification(...)

isCrispPushNotification(...)

openChat()

openHelpdeskArticle(...)

pushSessionEvent(...)

resetSession()

searchHelpdesk()

setCompany(...)

setNotificationsEnabled(...)

setSessionBool(...)

setSessionInt(...)

setSessionSegment(...)

setSessionString(...)

setShouldPromptForNotificationPermission(...)

setTokenId(...)

setUser(...)

addListener('chatClosed', ...)

addListener('chatOpened', ...)

addListener('messageReceived', ...)

addListener('messageSent', ...)

addListener('sessionLoaded', ...)

removeAllListeners()

Interfaces

ConfigureOptions

HandlePushNotificationOptions

IsCrispPushNotificationResult

IsCrispPushNotificationOptions

OpenHelpdeskArticleOptions

PushSessionEventOptions

SetCompanyOptions

SetCompanyEmployment

SetCompanyGeolocation

SetNotificationsEnabledOptions

SetSessionBoolOptions

SetSessionIntOptions

SetSessionSegmentOptions

SetSessionStringOptions

SetShouldPromptForNotificationPermissionOptions

SetTokenIdOptions

SetUserOptions

PluginListenerHandle

MessageReceivedEvent

MessageSentEvent

SessionLoadedEvent

Enums

SessionEventColor

Platform Support

Licensing

FAQ

Do I need a Crisp account to use this plugin?