The React Native Chat SDK can be installed in a few lines of code in any React Native or Expo app.

The Crisp Chat SDK allows you to add a chat widget to your React Native mobile app, enabling your customers to engage with your brand and easily communicate with your team. Just discovering Crisp and our SDK? You can learn more about our Chat SDKs right here.

• iOS Chat SDKLearn about the iOS Chat SDK.Read
• Android Chat SDKLearn about the Android Chat SDK.Read

Notice

Features

• iOS & Android support
• TypeScript support
• Full Expo support
• Push notifications support
• Event listeners
• Helpdesk integration
• Bot scenarios

Installation

For Expo Apps

Install the SDK using your preferred package manager:

npx expo install crisp-sdk-react-native

Version Targeting

The Crisp SDK requires minimum OS versions to function properly. Install expo-build-properties and configure your app.json:

npx expo install expo-build-properties

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "deploymentTarget": "15.1"
          },
          "android": {
            "minSdkVersion": 21
          }
        }
      ]
    ]
  }
}

For Bare React Native Apps

Prerequisites

Before starting, ensure you have:

• React Native 0.79+
• iOS deployment target 15.1+
• Android minSdkVersion 21+
• Node.js 18+

Step 1: Install Expo Modules

Run the following command in your project root:

npx install-expo-modules@latest

This command automatically configures your iOS and Android projects to support Expo modules.

Step 2: Install Crisp SDK

npm install crisp-sdk-react-native

Step 3: Platform Configuration

iOS:

cd ios && pod install

Android:

Ensure your android/app/build.gradle has:

android {
  compileSdkVersion 34

  defaultConfig {
    minSdkVersion 21
    targetSdkVersion 34
  }
}

How To Get Your Website ID?

Go to your Crisp Dashboard, and copy your Website ID:

Usage

Configure the SDK at app startup with your Website ID:

import { useEffect } from "react";
import { configure, show } from "crisp-sdk-react-native";

export default function App() {
  useEffect(() => {
    configure("YOUR_WEBSITE_ID");
  }, []);

  return (
    // Your app content
  );
}

Open Chat

Display the Crisp chat widget:

import { show } from "crisp-sdk-react-native";

function ChatButton() {
  const openChat = () => {
    show();
  };

  return <Button title="Open Chat" onPress={openChat} />;
}

User Identification

Set user information to personalize the chat experience:

import {
  setUserEmail, setUserNickname, setUserPhone, setUserAvatar,
  setUserCompany, setTokenId, resetSession,
} from "crisp-sdk-react-native";

// After user logs in
function identifyUser(user) {
  // Basic identification
  setUserEmail(user.email);
  setUserNickname(user.name);
  setUserPhone(user.phone); // E.164 format recommended: "+1234567890"
  setUserAvatar(user.avatarUrl);

  // Set company information
  setUserCompany({
    name: "Acme Corporation",
    url: "https://acme.com",
    companyDescription: "Leading provider of innovative solutions",
    employment: {
      title: "Software Engineer",
      role: "Engineering",
    },
    geolocation: {
      country: "France",
      city: "Paris",
    },
  });

  // Enable session persistence across devices
  setTokenId(user.id);
}

// On logout
function onLogout() {
  setTokenId(null);
  resetSession();
}

Session Data

Store custom data visible to operators in the Crisp dashboard:

import {
  setSessionString, setSessionBool, setSessionInt,
  setSessionSegment, setSessionSegments, getSessionIdentifier,
} from "crisp-sdk-react-native";

// Store different data types
setSessionString("plan", "premium");
setSessionBool("verified", true);
setSessionInt("loginCount", 42);

// Categorize users with segments
setSessionSegment("vip");

// Or set multiple segments at once
setSessionSegments(["premium", "early-adopter", "beta-tester"]);

// Get the current session identifier
const sessionId = await getSessionIdentifier();

Event Tracking

Track user actions in the chat timeline:

import { pushSessionEvent, CrispSessionEventColors } from "crisp-sdk-react-native";

// Track events
pushSessionEvent("Purchase completed", CrispSessionEventColors.GREEN);
pushSessionEvent("Payment failed", CrispSessionEventColors.RED);

Event Listeners

Subscribe to SDK events using the useCrispEvents hook:

import { useState } from "react";
import { show, useCrispEvents } from "crisp-sdk-react-native";

function ChatScreen() {
  const [unreadCount, setUnreadCount] = useState(0);

  useCrispEvents({
    onSessionLoaded: (sessionId) => {
      console.log("Crisp session ready:", sessionId);
    },
    onChatOpened: () => {
      console.log("Chat opened");
      setUnreadCount(0);
    },
    onChatClosed: () => {
      console.log("Chat closed");
    },
    onMessageSent: (message) => {
      console.log("User sent:", message.content);
    },
    onMessageReceived: (message) => {
      console.log("Received:", message.content);
      if (message.fromOperator) {
        setUnreadCount((count) => count + 1);
      }
    },
  });

  return <Button title={`Chat (${unreadCount})`} onPress={() => show()} />;
}

Helpdesk

Access your knowledge base:

import { searchHelpdesk, openHelpdeskArticle } from "crisp-sdk-react-native";

// Open helpdesk search
searchHelpdesk();

// Open a specific article
openHelpdeskArticle({
  id: "getting-started",
  locale: "en",
  title: "Getting Started",
  category: "Onboarding",
});

Bot Scenarios

Trigger automated conversation flows:

import { runBotScenario } from "crisp-sdk-react-native";

// Start a bot scenario configured in your Crisp dashboard
runBotScenario("welcome-flow");

Push Notifications

To enable push notifications, add the config plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "crisp-sdk-react-native",
        {
          "websiteId": "YOUR_WEBSITE_ID",
          "notifications": {
            "enabled": true,
            "mode": "sdk-managed"
          }
        }
      ]
    ]
  }
}

Push notifications require additional setup in your Crisp Dashboard (APNs for iOS, Firebase for Android). See the Push Notifications Setup Guide for detailed step-by-step instructions.

Available APIs

Configuration Methods

User Information Methods

Session Data Methods

Event Tracking Methods

Session Management

UI Methods

React Hook

Example Apps

Two fully functional example apps are included in the repository:

Troubleshooting

"Expo Go is not supported"

The Crisp SDK requires native modules. Use a development build instead:

npx expo run:ios
# or
npx expo run:android

Chat not appearing after show()

Ensure you've called configure() with a valid Website ID before calling show().

Push notifications not working

1. Verify the config plugin is properly configured in app.json
2. Rebuild with npx expo prebuild --clean
3. Ensure your Crisp dashboard has push notifications enabled
4. For iOS: Verify APNs certificates are configured in Crisp dashboard
5. For Android: Verify Firebase is properly configured

Session data not persisting

Use setTokenId() with a unique user identifier to enable session persistence across app reinstalls and devices.