Unofficial Capacitor plugin for Crisp.¹

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.
• 🤝 Compatibility: Looking for a different chat SDK? Check out the Intercom plugin.
• 📦 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!

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.

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 crisp-sdk-web
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.

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)

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.

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

android {
  defaultConfig {
    multiDexEnabled true
  }
}

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 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(...).

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

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 on iOS are delivered through Apple Push Notification service (APNs):

1. Enable the Push Notifications capability for your app target in Xcode.
2. 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.

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

No configuration required for this plugin.

The following examples show how to use 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 Crisp chatbox:

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

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

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

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

const setUser = async () => {
  await Crisp.setUser({
    email: 'jane.doe@example.com',
    emailSignature: 'YOUR_HMAC_SIGNATURE',
    nickname: 'Jane Doe',
  });
};

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 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);
  });
};

• configure(...)
• handlePushNotification(...)
• isCrispPushNotification(...)
• openChat()
• openHelpdeskArticle(...)
• pushSessionEvent(...)
• resetSession()
• searchHelpdesk()
• setCompany(...)
• setLocale(...)
• setNotificationsEnabled(...)
• setSessionBool(...)
• setSessionInt(...)
• setSessionSegment(...)
• setSessionString(...)
• setShouldPromptForNotificationPermission(...)
• setTokenId(...)
• setUser(...)
• addListener('chatClosed', ...)
• addListener('chatOpened', ...)
• addListener('messageReceived', ...)
• addListener('messageSent', ...)
• addListener('sessionLoaded', ...)
• removeAllListeners()
• Interfaces
• Enums

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

Configure the plugin with your Crisp website ID.

This method must be called before any other method.

Since: 0.1.0

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.

Since: 0.1.0

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

Check whether an incoming push notification belongs to Crisp.

Only available on Android.

Returns: Promise<IsCrispPushNotificationResult>

Since: 0.1.0

openChat() => Promise<void>

Open the chat.

Since: 0.1.0

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

Open a specific helpdesk article.

Since: 0.1.0

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

Push a session event to the current session.

Since: 0.1.0

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

Open the helpdesk with the search view.

Since: 0.1.0

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

Set the company of the current user.

Since: 0.1.0

setLocale(options: SetLocaleOptions) => Promise<void>

Set the locale of the chatbox.

On Android and iOS, the chatbox follows the language of the app.

Only available on Web.

Since: 0.1.2

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

Enable or disable push notifications.

Only available on Android.

Since: 0.1.0

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

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

Since: 0.1.0

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

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

Since: 0.1.0

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

Set the segment of the current session.

Since: 0.1.0

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

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

Since: 0.1.0

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

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

Only available on iOS.

Since: 0.1.0

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(...).

Since: 0.1.0

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

Set the information of the current user.

Since: 0.1.0

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

Called when the chat is closed.

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

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

Called when the chat is opened.

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

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

Called when a message is received from the operator.

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

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

Called when a message is sent by the user.

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

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.

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

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

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 Crisp Android and iOS SDKs do not provide a locale override, so the setLocale(...) method is only available on the web. The native chatbox follows the language of the app. To change it at runtime, change the language of the app, e.g. with the App Language plugin.

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

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

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.

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

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.

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.

• Formbricks: Unofficial Capacitor plugin for Formbricks to run in-app surveys.
• Intercom: Unofficial Capacitor plugin for the Intercom live chat and customer support platform.
• PostHog: Unofficial Capacitor plugin for the PostHog product analytics platform.

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

See CHANGELOG.md.

See LICENSE.

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.