capacitor-crisp

Add Crisp live chat to your Capacitor app with the native Crisp SDKs. Open the messenger, identify users, push events and handle Crisp push notifications on iOS and Android.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-crisp in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-crisp to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Messenger: configure() with your website ID, then openMessenger().
• User data: setUser(), setCompany(), setTokenID(), setSegment() and custom setString() or setInt() fields.
• Events and messages: pushEvent(), sendMessage() and listeners like messageReceived and chatOpened.
• Push notifications: registerPushToken(), isCrispPushNotification() and handlePushNotification().
• Sessions: reset() clears the current session.
• Platforms: iOS and Android. Native Crisp SDKs on iOS and Android. Push helpers are not available on web.

Why Capacitor Crisp?

The only free Capacitor plugin for integrating Crisp.chat's native SDK into your mobile apps. Crisp is a powerful customer support and messaging platform, and this plugin provides:

• Native SDK integration - Full access to Crisp's native mobile SDKs for iOS and Android
• Rich messaging features - Live chat, user profiles, custom data, events, and segmentation
• Two-way communication - Send messages programmatically and track user behavior
• Complete API - Full feature parity with Crisp's JavaScript API

Perfect for apps needing customer support, helpdesk functionality, or user engagement tools.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/crisp/

Compatibility

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

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

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/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 @capgo/capacitor-crisp
npx cap sync

Init

Call configure in your code Before any other method :

import { CapacitorCrisp } from '@capgo/capacitor-crisp';

CapacitorCrisp.configure({websiteID: '******-****-****-****-********'})

iOS

To enable your users to take and upload photos to the chat as well as download photos to their photo library, add :

Privacy - Camera Usage Description (NSCameraUsageDescription)

Privacy - Photo Library Additions Usage Description (NSPhotoLibraryAddUsageDescription)

to your app's Info.plist.

Android Integration

Nothing special to do for the chatbox itself.

Push Notifications

Crisp push notifications require credentials in your Crisp dashboard under Settings > Chatbox Settings > Push Notifications (APNs for iOS, Firebase for Android). See the Crisp iOS and Crisp Android guides for dashboard setup.

Native setup (recommended)

The plugin handles timing-sensitive setup natively:

• iOS: APNs tokens from @capacitor/push-notifications are forwarded to Crisp automatically.
• Android: enableNotifications() runs automatically inside configure().

You still need platform setup:

1. Enable the Push Notifications capability in Xcode (iOS).
2. Configure Firebase (google-services.json) and add firebase-messaging to your Android app (Android).
3. Call CapacitorCrisp.configure({ websiteID: 'YOUR_WEBSITE_ID' }) before opening the messenger.

With @capacitor/push-notifications

import { CapacitorCrisp } from '@capgo/capacitor-crisp';
import { PushNotifications } from '@capacitor/push-notifications';

await CapacitorCrisp.configure({ websiteID: 'YOUR_WEBSITE_ID' });
await PushNotifications.register();

// Optional JS fallback (iOS is already handled natively)
await PushNotifications.addListener('registration', async ({ value }) => {
  await CapacitorCrisp.registerPushToken({ token: value });
});

// Forward foreground Crisp pushes so messageReceived can update your unread badge.
await PushNotifications.addListener('pushNotificationReceived', async (notification) => {
  const { isCrisp } = await CapacitorCrisp.isCrispPushNotification({ data: notification.data });
  if (isCrisp) {
    await CapacitorCrisp.handlePushNotification({ data: notification.data, openChatbox: false });
  }
});

await PushNotifications.addListener('pushNotificationActionPerformed', async (event) => {
  const { isCrisp } = await CapacitorCrisp.isCrispPushNotification({ data: event.notification.data });
  if (isCrisp) {
    await CapacitorCrisp.handlePushNotification({ data: event.notification.data });
  }
});

On iOS, disable Crisp auto-prompting if you manage permissions yourself:

await CapacitorCrisp.setShouldPromptForNotificationPermission({ enabled: false });

Android: shared FirebaseMessagingService

If you already have a custom FirebaseMessagingService, forward Crisp events with CrispFcmHelper:

import ee.forgr.plugin.crisp.CrispFcmHelper;
import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;

public class MyFirebaseMessagingService extends FirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (CrispFcmHelper.isCrispNotification(remoteMessage)) {
            CrispFcmHelper.onMessageReceived(this, remoteMessage);
        }
    }

    @Override
    public void onNewToken(String token) {
        CrispFcmHelper.onNewToken(this, token);
    }
}

Android: Crisp-only notifications

If you do not use another push provider, declare CrispNotificationService in your app AndroidManifest.xml:

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

iOS: native AppDelegate (optional)

You can also forward the APNs token directly in AppDelegate.swift:

import Crisp

func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    CrispSDK.setDeviceToken(deviceToken)
}

Open chatbox

import { CapacitorCrisp } from '@capgo/capacitor-crisp';

CapacitorCrisp.openMessenger()

API

• configure(...)
• openMessenger()
• setTokenID(...)
• setUser(...)
• pushEvent(...)
• setCompany(...)
• setInt(...)
• setString(...)
• sendMessage(...)
• setSegment(...)
• reset()
• addListener('messageReceived', ...)
• addListener('messageSent', ...)
• addListener('sessionLoaded', ...)
• addListener('chatOpened', ...)
• addListener('chatClosed', ...)
• removeAllListeners()
• registerPushToken(...)
• enableNotifications()
• isCrispPushNotification(...)
• handlePushNotification(...)
• setShouldPromptForNotificationPermission(...)
• openChatboxFromNotification()
• getPluginVersion()
• Interfaces
• Type Aliases

Crisp Chat SDK Plugin for Capacitor. Provides live chat and customer support functionality through Crisp.chat.

configure(...)

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

Configure the Crisp SDK with your website ID. Must be called before using any other methods.

openMessenger()

openMessenger() => Promise<void>

Open the Crisp messenger chat window. Shows the chat interface to the user.

setTokenID(...)

setTokenID(data: { tokenID: string; }) => Promise<void>

Set a unique token ID for the current user session. Used to identify and restore previous conversations.

setUser(...)

setUser(data: { nickname?: string; phone?: string; email?: string; signature?: string; avatar?: string; }) => Promise<void>

Set user information for the current session. Updates the user profile visible to support agents.

pushEvent(...)

pushEvent(data: { name: string; color: eventColor; }) => Promise<void>

Push a custom event to Crisp. Useful for tracking user actions and behavior.

setCompany(...)

setCompany(data: { name: string; url?: string; description?: string; employment?: [title: string, role: string]; geolocation?: [country: string, city: string]; }) => Promise<void>

Set company information for the current session. Associates the user with a company in Crisp.

setInt(...)

setInt(data: { key: string; value: number; }) => Promise<void>

Set a custom integer data field. Stores numerical data associated with the user session.

setString(...)

setString(data: { key: string; value: string; }) => Promise<void>

Set a custom string data field. Stores text data associated with the user session.

sendMessage(...)

sendMessage(data: { value: string; }) => Promise<void>

Send a message from the user to the chat. Programmatically send a message as if the user typed it.

setSegment(...)

setSegment(data: { segment: string; }) => Promise<void>

Set a user segment for targeting and organization. Used to categorize users in the Crisp dashboard.

reset()

reset() => Promise<void>

Reset the Crisp session. Clears all user data and starts a fresh session. Useful when user logs out.

addListener('messageReceived', ...)

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

Listen for incoming Crisp messages.

Returns: Promise<PluginListenerHandle>

addListener('messageSent', ...)

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

Listen for messages sent through Crisp.

Returns: Promise<PluginListenerHandle>

addListener('sessionLoaded', ...)

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

Listen for the native Crisp session loading.

Returns: Promise<PluginListenerHandle>

addListener('chatOpened', ...)

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

Listen for the Crisp chatbox opening.

Returns: Promise<PluginListenerHandle>

addListener('chatClosed', ...)

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

Listen for the Crisp chatbox closing.

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all registered listeners for this plugin.

registerPushToken(...)

registerPushToken(data: { token: string; }) => Promise<void>

Register the device push token (APNs on iOS, FCM on Android) with Crisp. Optional fallback when you cannot use native token forwarding. On iOS, the plugin forwards APNs tokens from @capacitor/push-notifications automatically via native hooks.

enableNotifications()

enableNotifications() => Promise<void>

Enable Crisp push notifications on Android. Called automatically during configure() on Android. This JS method is an optional manual override. No-op on iOS and web.

isCrispPushNotification(...)

isCrispPushNotification(data: { data: Record<string, string>; }) => Promise<{ isCrisp: boolean; }>

Check whether a push notification payload was sent by Crisp. Useful when sharing push handling with @capacitor/push-notifications.

Returns: Promise<{ isCrisp: boolean; }>

handlePushNotification(...)

handlePushNotification(data: { data: Record<string, string>; openChatbox?: boolean; }) => Promise<void>

Handle a Crisp push notification payload. On Android, opens the chatbox by default when the user taps a notification. On iOS, processes the payload through the Crisp SDK. Emits messageReceived with fromPushNotification: true for Crisp payloads, which lets apps update unread badges when the chatbox is closed.

setShouldPromptForNotificationPermission(...)

setShouldPromptForNotificationPermission(data: { enabled: boolean; }) => Promise<void>

Control whether Crisp auto-prompts for notification permission on iOS. No-op on Android and web.

openChatboxFromNotification()

openChatboxFromNotification() => Promise<{ opened: boolean; }>

Open the Crisp chatbox from a notification tap intent on Android. Call from your main activity when handling notification open actions. No-op on iOS and web.

Returns: Promise<{ opened: boolean; }>

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the plugin version number.

Returns: Promise<{ version: string; }>

Interfaces

ConfigureOptions

Configuration for initializing Crisp.

PluginListenerHandle

CrispMessageEvent

Payload emitted when a Crisp message event is received from the native SDK or from a forwarded Crisp push notification.

CrispSessionLoadedEvent

Payload emitted when the Crisp session is loaded.

Type Aliases

eventColor

Available colors for Crisp events. Used to visually categorize events in the Crisp dashboard.

'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'brown' | 'grey' | 'black'

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }