{"id":47144888,"url":"https://github.com/crisp-im/crisp-sdk-react-native","last_synced_at":"2026-03-12T23:33:09.626Z","repository":{"id":338829123,"uuid":"1091806203","full_name":"crisp-im/crisp-sdk-react-native","owner":"crisp-im","description":":package: Include the Crisp chat widget in your React Native app","archived":false,"fork":false,"pushed_at":"2026-03-06T12:18:23.000Z","size":7352,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-06T12:47:26.553Z","etag":null,"topics":["chatbox","crisp","react-native","sdk"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/crisp-sdk-react-native","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crisp-im.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T14:47:53.000Z","updated_at":"2026-03-06T12:21:55.000Z","dependencies_parsed_at":"2026-02-17T00:04:28.657Z","dependency_job_id":null,"html_url":"https://github.com/crisp-im/crisp-sdk-react-native","commit_stats":null,"previous_names":["crisp-im/crisp-sdk-react-native"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/crisp-im/crisp-sdk-react-native","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisp-im%2Fcrisp-sdk-react-native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisp-im%2Fcrisp-sdk-react-native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisp-im%2Fcrisp-sdk-react-native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisp-im%2Fcrisp-sdk-react-native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crisp-im","download_url":"https://codeload.github.com/crisp-im/crisp-sdk-react-native/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crisp-im%2Fcrisp-sdk-react-native/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30449130,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T21:31:01.033Z","status":"ssl_error","status_checked_at":"2026-03-12T21:30:43.161Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbox","crisp","react-native","sdk"],"created_at":"2026-03-12T23:33:09.036Z","updated_at":"2026-03-12T23:33:09.611Z","avatar_url":"https://github.com/crisp-im.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://crisp.chat/en/sdk/react-native/\"\u003e\n    \u003cimg width=\"659\" alt=\"crisp-banner\" src=\"https://github.com/user-attachments/assets/ac273b9a-5713-4fb6-ab1e-7214a018731e\" /\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n  \u003ch3 align=\"center\"\u003ecrisp-sdk-react-native\u003c/h3\u003e\n  \u003cp align=\"center\"\u003eThe official Crisp SDK for React Native \u0026mdash; Add live chat to your Expo \u0026 React Native apps\u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/crisp-sdk-react-native\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/crisp-sdk-react-native.svg\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/crisp-im/crisp-sdk-react-native/blob/master/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/l/crisp-sdk-react-native.svg\" alt=\"license\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Expo%20SDK-51%2B-blue\" alt=\"Expo SDK 51+\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platforms-iOS%20%7C%20Android-lightgrey\" alt=\"platforms\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://crisp.chat/en/sdk/\"\u003e\u003cb\u003eSee Crisp Support Chat SDKs\u003c/b\u003e\u003c/a\u003e \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003ca href=\"https://crisp.chat/en/sdk/react-native/\"\u003e\u003cb\u003eReact Native Support Chat SDK\u003c/b\u003e\u003c/a\u003e \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003ca href=\"https://docs.crisp.chat/guides/chatbox-sdks/react-native-sdk/\"\u003e\u003cb\u003eDeveloper Docs\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\u003cb\u003eTrusted by\u003c/b\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/4b824e2a-018f-42a5-850e-34cb588adeb2\" alt=\"Fruitz\" height=\"40\" align=\"center\" /\u003e\n  \u003cb\u003eFruitz\u003c/b\u003e\n  \u0026nbsp;\u0026middot;\u0026nbsp;\n  and many more companies rely on Crisp to power their in-app customer support.\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eDemo\u003c/b\u003e\n\u003c/p\u003e\n\n\u003c!-- TODO: Upload docs/Demo-Crisp-React-Native.mp4 via GitHub's web editor (drag-and-drop) and replace the src below with the generated URL --\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/ac64f6f1-91ae-4804-93e5-b747145d81fe\" controls width=\"300\"\u003e\u003c/video\u003e\n\u003c/div\u003e\n\n---\n\n\u003e [!WARNING]\n\u003e **Minimum Expo SDK version**\n\u003e\n\u003e | SDK Version | Expo Compatibility |\n\u003e |---|---|\n\u003e | **0.2.0+** | Expo SDK 54+ (AGP 8.9.1+ required by Crisp Android SDK 2.0.16+) |\n\u003e | **0.1.4** | Expo SDK 51+ |\n\u003e\n\u003e If you are on Expo 53 or older, pin to version 0.1.4:\n\u003e ```bash\n\u003e npx expo install crisp-sdk-react-native@0.1.4\n\u003e ```\n\n\u003e [!WARNING]\n\u003e **Expo Go is Not Supported**\n\u003e\n\u003e The Crisp SDK uses native modules that are not available in Expo Go. You must use a [development build](https://docs.expo.dev/develop/development-builds/introduction/):\n\u003e\n\u003e ```bash\n\u003e npx expo run:ios\n\u003e # or\n\u003e npx expo run:android\n\u003e ```\n\n---\n\n## Installation\n\n### For Expo Apps\n\nInstall the SDK using your preferred package manager:\n\n```bash\n# Using bun\nbunx expo install crisp-sdk-react-native\n\n# Using pnpm\npnpm dlx expo install crisp-sdk-react-native\n\n# Using npm\nnpx expo install crisp-sdk-react-native\n\n# Using yarn\nyarn dlx expo install crisp-sdk-react-native\n```\n\n### For Bare React Native Apps\n\nThis guide is for React Native developers who want to integrate Crisp using the Expo SDK in a project that doesn't use Expo as its development framework.\n\n#### Prerequisites\n\nBefore starting, ensure you have:\n\n- React Native 0.74+\n- iOS deployment target 15.1+\n- Android minSdkVersion 24+\n- Node.js 18+\n\n#### Step 1: Install Expo Modules\n\nRun the following command in your project root:\n\n```bash\nnpx install-expo-modules@latest\n```\n\nThis command automatically configures your iOS and Android projects to support Expo modules.\n\n\u003e [!NOTE]\n\u003e For comprehensive installation details or manual installation steps, refer to [Expo's official guide](https://docs.expo.dev/bare/installing-expo-modules/).\n\n#### Step 2: Install Crisp SDK\n\n```bash\n# Using npm\nnpm install crisp-sdk-react-native\n\n# Using yarn\nyarn add crisp-sdk-react-native\n\n# Using pnpm\npnpm add crisp-sdk-react-native\n\n# Using bun\nbun add crisp-sdk-react-native\n```\n\n#### Step 3: Platform Configuration\n\n**iOS:**\n\n```bash\ncd ios \u0026\u0026 pod install\n```\n\n**Android:**\n\nEnsure your `android/app/build.gradle` has:\n\n```gradle\nandroid {\n    compileSdkVersion 36\n\n    defaultConfig {\n        minSdkVersion 24\n        targetSdkVersion 36\n    }\n}\n```\n\n---\n\n## Configuration\n\n### Get Your Website ID\n\nTo use the Crisp SDK, you need your Website ID from the Crisp Dashboard.\n\n1. [Sign up for a free account](https://app.crisp.chat/initiate/signup/) on Crisp (or log in)\n2. Go to **Settings** \u003e **Website Settings** \u003e **Setup instructions**\n3. Copy your Website ID\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e\u003cimg width=\"1797\" height=\"872\" alt=\"Setup and Integrations\" src=\"https://github.com/user-attachments/assets/a68dd11e-84ed-4e9f-a68c-ec63fc58c61a\" /\u003e\u003c/em\u003e\n\u003c/p\u003e\n\n### Initialize Crisp\n\nConfigure the SDK at app startup with your Website ID:\n\n```typescript\nimport { useEffect } from \"react\";\nimport { configure } from \"crisp-sdk-react-native\";\n\nexport default function App() {\n  useEffect(() =\u003e {\n    configure(\"YOUR_WEBSITE_ID\");\n  }, []);\n\n  return (\n    // Your app content\n  );\n}\n```\n\n### Push Notifications (Config Plugin)\n\nTo enable push notifications, add the config plugin to your `app.json` or `app.config.js`:\n\n```json\n{\n  \"expo\": {\n    \"plugins\": [\n      [\n        \"crisp-sdk-react-native\",\n        {\n          \"websiteId\": \"YOUR_WEBSITE_ID\",\n          \"notifications\": {\n            \"enabled\": true,\n            \"mode\": \"sdk-managed\"\n          }\n        }\n      ]\n    ]\n  }\n}\n```\n\n#### Plugin Options\n\n| Option                  | Type                             | Default         | Description                                                                  |\n| ----------------------- | -------------------------------- | --------------- | ---------------------------------------------------------------------------- |\n| `websiteId`             | `string`                         | -               | Your Crisp Website ID. **Required** when notifications are enabled.          |\n| `notifications.enabled` | `boolean`                        | `false`         | Enable push notifications for Crisp Chat.                                    |\n| `notifications.mode`    | `\"sdk-managed\" \\| \"coexistence\"` | `\"sdk-managed\"` | Notification handling mode. See [Coexistence Mode](#coexistence-mode) below. |\n\n\u003e [!IMPORTANT]\n\u003e The `websiteId` is **required** when `notifications.enabled` is `true`. The plugin will throw an error if it's missing.\n\n#### What the Plugin Configures\n\n**iOS:**\n\n- Adds `remote-notification` to UIBackgroundModes\n- Adds `aps-environment` entitlement for APNs\n- Registers for remote notifications on app launch\n- Forwards device token to Crisp SDK\n\n**Android:**\n\n- Adds `CrispNotificationService` to AndroidManifest\n- Adds `firebase-messaging` dependency\n- Configures Crisp SDK with websiteId\n\n\u003e [!NOTE]\n\u003e After enabling notifications, rebuild your app with `npx expo prebuild --clean` followed by `npx expo run:ios` or `npx expo run:android`.\n\n#### Crisp Dashboard Configuration\n\nPush notifications require additional setup in your Crisp Dashboard (APNs for iOS, Firebase for Android).\n\nSee the [Push Notifications Setup Guide](./docs/PUSH_NOTIFICATIONS.md) for detailed step-by-step instructions.\n\n#### Coexistence Mode\n\nBy default, Crisp handles all push notification routing exclusively (`\"sdk-managed\"` mode). If your app uses another notification system (like `expo-notifications`, `@react-native-firebase/messaging`, or OneSignal), use `\"coexistence\"` mode to let both systems work together:\n\n```json\n{\n  \"expo\": {\n    \"plugins\": [\n      [\n        \"crisp-sdk-react-native\",\n        {\n          \"websiteId\": \"YOUR_WEBSITE_ID\",\n          \"notifications\": {\n            \"enabled\": true,\n            \"mode\": \"coexistence\"\n          }\n        }\n      ]\n    ]\n  }\n}\n```\n\nIn coexistence mode, the plugin:\n\n- **Android**: Generates a chained `FirebaseMessagingService` that routes Crisp notifications to the Crisp SDK and delegates all others to `expo-notifications` (or Firebase directly)\n- **iOS**: Implements a `UNUserNotificationCenterDelegate` that filters Crisp notifications and forwards the rest to the previous delegate (chain of responsibility)\n\n**JS API for coexistence mode:**\n\n```typescript\nimport {\n  registerPushToken,\n  isCrispPushNotification,\n  setShouldPromptForNotificationPermission,\n} from \"crisp-sdk-react-native\";\n\n// Register a push token obtained from your notification system\nregisterPushToken(expoPushToken);\n\n// Check if a notification payload is from Crisp\nconst isCrisp = isCrispPushNotification(notificationData);\n\n// Control whether Crisp auto-prompts for notification permissions (iOS only)\nsetShouldPromptForNotificationPermission(false);\n```\n\n**Listen for Crisp notifications in the foreground (iOS only):**\n\n```typescript\nimport { useCrispEvents } from \"crisp-sdk-react-native\";\n\nuseCrispEvents({\n  onPushNotificationReceived: ({ title, body }) =\u003e {\n    console.log(\"Crisp notification:\", title, body);\n    // Update badge count, show toast, log analytics, etc.\n  },\n});\n```\n\n\u003e [!NOTE]\n\u003e `onPushNotificationReceived` is currently **iOS only**. On Android, the Crisp SDK does not expose a foreground notification callback — notifications are handled entirely at the native `FirebaseMessagingService` level.\n\n\u003e [!NOTE]\n\u003e In coexistence mode, the native routing is automatic — you don't need to write JS filtering code. The JS API methods (`registerPushToken`, `isCrispPushNotification`) are optional utilities for advanced use cases.\n\n---\n\n## Usage Examples\n\n### Open Chat\n\nDisplay the Crisp chat widget:\n\n```typescript\nimport { show, openChat } from \"crisp-sdk-react-native\";\n\n// Opens the widget (remembers the last active tab)\nshow();\n\n// Always opens on the Chat tab, regardless of the last active tab\nopenChat();\n```\n\n\u003e [!NOTE]\n\u003e `openChat()` forces the Chat tab on **iOS only**. On Android, the native SDK always opens on the Chat tab by default, so `openChat()` and `show()` behave the same way.\n\n### User Identification\n\nSet user information to personalize the chat experience:\n\n```typescript\nimport {\n  setUserEmail,\n  setUserNickname,\n  setUserPhone,\n  setUserAvatar,\n  setUserCompany,\n  setTokenId,\n  resetSession,\n} from \"crisp-sdk-react-native\";\n\n// After user logs in\nfunction identifyUser(user) {\n  // Basic identification\n  setUserEmail(user.email);\n  setUserNickname(user.name);\n  setUserPhone(user.phone); // E.164 format recommended: \"+1234567890\"\n  setUserAvatar(user.avatarUrl);\n\n  // Set company information\n  setUserCompany({\n    name: \"Acme Corporation\",\n    url: \"https://acme.com\",\n    companyDescription: \"Leading provider of innovative solutions\",\n    employment: {\n      title: \"Software Engineer\",\n      role: \"Engineering\",\n    },\n    geolocation: {\n      country: \"France\",\n      city: \"Paris\",\n    },\n  });\n\n  // Enable session persistence across devices\n  setTokenId(user.id);\n}\n\n// On logout\nfunction onLogout() {\n  setTokenId(null);\n  resetSession();\n}\n```\n\n### Session Data\n\nStore custom data visible to operators in the Crisp dashboard:\n\n```typescript\nimport {\n  setSessionString,\n  setSessionBool,\n  setSessionInt,\n  setSessionSegment,\n  setSessionSegments,\n  getSessionIdentifier,\n} from \"crisp-sdk-react-native\";\n\n// Store different data types\nsetSessionString(\"plan\", \"premium\");\nsetSessionBool(\"verified\", true);\nsetSessionInt(\"loginCount\", 42);\n\n// Categorize users with segments\nsetSessionSegment(\"vip\");\n\n// Or set multiple segments at once\nsetSessionSegments([\"premium\", \"early-adopter\", \"beta-tester\"]);\n\n// Replace all existing segments\nsetSessionSegments([\"enterprise\"], true);\n\n// Get the current session identifier\nconst sessionId = await getSessionIdentifier();\nconsole.log(\"Session ID:\", sessionId);\n```\n\n### Event Tracking\n\nTrack user actions in the chat timeline:\n\n```typescript\nimport {\n  pushSessionEvent,\n  pushSessionEvents,\n  CrispSessionEventColors,\n} from \"crisp-sdk-react-native\";\n\n// Track a single event\npushSessionEvent(\"Purchase completed\", CrispSessionEventColors.GREEN);\npushSessionEvent(\"Payment failed\", CrispSessionEventColors.RED);\n\n// Track multiple events at once\npushSessionEvents([\n  { name: \"Viewed pricing page\", color: CrispSessionEventColors.BLUE },\n  { name: \"Started free trial\", color: CrispSessionEventColors.GREEN },\n  { name: \"Upgraded to Pro\", color: CrispSessionEventColors.PURPLE },\n]);\n```\n\n### Event Listeners\n\nSubscribe to SDK events using the `useCrispEvents` hook:\n\n```typescript\nimport { useState } from \"react\";\nimport { View, Button } from \"react-native\";\nimport { show, useCrispEvents } from \"crisp-sdk-react-native\";\n\nfunction ChatScreen() {\n  const [unreadCount, setUnreadCount] = useState(0);\n\n  useCrispEvents({\n    onSessionLoaded: (sessionId) =\u003e {\n      console.log(\"Crisp session ready:\", sessionId);\n    },\n    onChatOpened: () =\u003e {\n      console.log(\"Chat opened\");\n      setUnreadCount(0); // Reset unread count\n    },\n    onChatClosed: () =\u003e {\n      console.log(\"Chat closed\");\n    },\n    onMessageSent: (message) =\u003e {\n      console.log(\"User sent:\", message.content);\n    },\n    onMessageReceived: (message) =\u003e {\n      console.log(\"Received:\", message.content);\n      if (message.fromOperator) {\n        setUnreadCount((count) =\u003e count + 1);\n      }\n    },\n  });\n\n  return (\n    \u003cView\u003e\n      \u003cButton title={`Open Chat (${unreadCount})`} onPress={() =\u003e show()} /\u003e\n    \u003c/View\u003e\n  );\n}\n```\n\n### Show Messages\n\nDisplay messages programmatically in the chat:\n\n```typescript\nimport { showMessage } from \"crisp-sdk-react-native\";\n\n// Simple text message\nshowMessage({\n  type: \"text\",\n  text: \"Hello! How can I help you today?\",\n});\n\n// File attachment\nshowMessage({\n  type: \"file\",\n  url: \"https://example.com/document.pdf\",\n  name: \"Document.pdf\",\n  mimeType: \"application/pdf\",\n});\n\n// Animation (GIF)\nshowMessage({\n  type: \"animation\",\n  url: \"https://example.com/celebration.gif\",\n  mimeType: \"image/gif\",\n});\n\n// Audio message\nshowMessage({\n  type: \"audio\",\n  url: \"https://example.com/voice-note.mp3\",\n  mimeType: \"audio/mpeg\",\n  duration: 15,\n});\n\n// Picker for user choice\nshowMessage({\n  type: \"picker\",\n  id: \"satisfaction\",\n  text: \"How satisfied are you with our service?\",\n  choices: [\n    { value: \"happy\", label: \"Very satisfied\" },\n    { value: \"neutral\", label: \"Neutral\" },\n    { value: \"sad\", label: \"Not satisfied\" },\n  ],\n});\n\n// Field for user input\nshowMessage({\n  type: \"field\",\n  id: \"email\",\n  text: \"What's your email address?\",\n  explain: \"We'll send you updates\",\n  required: true,\n});\n\n// Carousel with multiple items\nshowMessage({\n  type: \"carousel\",\n  text: \"Check out our products\",\n  targets: [\n    {\n      title: \"Product A\",\n      description: \"Great for beginners\",\n      imageUrl: \"https://example.com/product-a.jpg\",\n      actionUrl: \"https://example.com/products/a\",\n    },\n    {\n      title: \"Product B\",\n      description: \"For power users\",\n      imageUrl: \"https://example.com/product-b.jpg\",\n      actionUrl: \"https://example.com/products/b\",\n    },\n  ],\n});\n```\n\n### Helpdesk\n\nAccess your knowledge base:\n\n```typescript\nimport { searchHelpdesk, openHelpdeskArticle } from \"crisp-sdk-react-native\";\n\n// Open helpdesk search (automatically opens the chat)\nsearchHelpdesk();\n\n// Open a specific article (automatically opens the chat)\nopenHelpdeskArticle({\n  id: \"getting-started\",\n  locale: \"en\",\n  title: \"Getting Started\", // Optional\n  category: \"Onboarding\", // Optional\n});\n```\n\n### Bot Scenarios\n\nTrigger automated conversation flows:\n\n```typescript\nimport { runBotScenario } from \"crisp-sdk-react-native\";\n\n// Start a bot scenario configured in your Crisp dashboard\nrunBotScenario(\"welcome-flow\");\n```\n\n### Debug Logging\n\nEnable native SDK logging to help debug integration issues:\n\n```typescript\nimport {\n  setLogLevel,\n  CrispLogLevel,\n  useCrispEvents,\n} from \"crisp-sdk-react-native\";\n\n// Set the minimum log level (default: WARN)\nsetLogLevel(CrispLogLevel.DEBUG);\n\n// Listen to log messages from the native SDK\nuseCrispEvents({\n  onLogReceived: (log) =\u003e {\n    console.log(`[Crisp] [${log.level}] ${log.tag}: ${log.message}`);\n  },\n});\n```\n\nAvailable log levels (from most to least verbose):\n\n| Level     | Value | Description                    |\n| --------- | ----- | ------------------------------ |\n| `VERBOSE` | 0     | Most verbose, all log messages |\n| `DEBUG`   | 1     | Debug information              |\n| `INFO`    | 2     | Informational messages         |\n| `WARN`    | 3     | Warnings (default)             |\n| `ERROR`   | 4     | Error messages only            |\n| `ASSERT`  | 5     | Critical assertion failures    |\n\n\u003e [!NOTE]\n\u003e Set the log level **after** calling `configure()`. Only logs at or above the configured level are emitted to the `onLogReceived` callback.\n\n---\n\n## API Reference\n\n### Configuration Methods\n\n| Method                 | Description                                                                  | Parameters                | Return |\n| ---------------------- | ---------------------------------------------------------------------------- | ------------------------- | ------ |\n| `configure(websiteId)` | Initialize the SDK with your Website ID. Must be called once at app startup. | `websiteId: string`       | `void` |\n| `setTokenId(tokenId)`  | Set a token for session persistence across app reinstalls and devices.       | `tokenId: string \\| null` | `void` |\n\n### Logger Methods\n\n| Method               | Description                                                                                                    | Parameters             | Return |\n| -------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |\n| `setLogLevel(level)` | Set the minimum log level for native SDK logging. Logs at or above this level are emitted via `onLogReceived`. | `level: CrispLogLevel` | `void` |\n\n### User Information Methods\n\n| Method                            | Description                                                             | Parameters                                  | Return |\n| --------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------- | ------ |\n| `setUserEmail(email, signature?)` | Set the user's email address. Optional HMAC signature for verification. | `email: string, signature?: string \\| null` | `void` |\n| `setUserNickname(name)`           | Set the user's display name in the chat.                                | `name: string`                              | `void` |\n| `setUserPhone(phone)`             | Set the user's phone number. E.164 format recommended.                  | `phone: string`                             | `void` |\n| `setUserAvatar(url)`              | Set the user's avatar image URL.                                        | `url: string`                               | `void` |\n| `setUserCompany(company)`         | Set the user's company information.                                     | `company: Company`                          | `void` |\n\n### Session Data Methods\n\n| Method                                     | Description                                                                | Parameters                                | Return                    |\n| ------------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------- | ------------------------- |\n| `setSessionString(key, value)`             | Store a custom string value in session data.                               | `key: string, value: string`              | `void`                    |\n| `setSessionBool(key, value)`               | Store a custom boolean value in session data.                              | `key: string, value: boolean`             | `void`                    |\n| `setSessionInt(key, value)`                | Store a custom integer value in session data.                              | `key: string, value: number`              | `void`                    |\n| `setSessionSegment(segment)`               | Set a single segment to categorize the user.                               | `segment: string`                         | `void`                    |\n| `setSessionSegments(segments, overwrite?)` | Set multiple segments. If `overwrite` is true, replaces existing segments. | `segments: string[], overwrite?: boolean` | `void`                    |\n| `getSessionIdentifier()`                   | Get the current session identifier.                                        | -                                         | `Promise\u003cstring \\| null\u003e` |\n\n### Event Tracking Methods\n\n| Method                          | Description                                       | Parameters                                     | Return |\n| ------------------------------- | ------------------------------------------------- | ---------------------------------------------- | ------ |\n| `pushSessionEvent(name, color)` | Track a single event in the user's chat timeline. | `name: string, color: CrispSessionEventColors` | `void` |\n| `pushSessionEvents(events)`     | Track multiple events at once.                    | `events: SessionEvent[]`                       | `void` |\n\n### Session Management\n\n| Method           | Description                                               | Parameters | Return |\n| ---------------- | --------------------------------------------------------- | ---------- | ------ |\n| `resetSession()` | Clear the current session and start a fresh conversation. | -          | `void` |\n\n### UI Methods\n\n| Method                         | Description                                             | Parameters                        | Return |\n| ------------------------------ | ------------------------------------------------------- | --------------------------------- | ------ |\n| `show()`                       | Open the Crisp chat widget (last active tab).           | -                                 | `void` |\n| `openChat()`                   | Open the Crisp chat widget always on the Chat tab (iOS only, see note below). | -                | `void` |\n| `searchHelpdesk()`             | Open the helpdesk search interface and the chat widget. | -                                 | `void` |\n| `openHelpdeskArticle(options)` | Open a specific helpdesk article and the chat widget.   | `options: HelpdeskArticleOptions` | `void` |\n| `runBotScenario(scenarioId)`   | Trigger an automated bot scenario.                      | `scenarioId: string`              | `void` |\n\n### Push Notification Methods (Coexistence Mode)\n\n| Method                                              | Description                                                                       | Parameters                     | Return    |\n| --------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------ | --------- |\n| `registerPushToken(token)`                          | Register a push token (FCM/APNs) with Crisp.                                      | `token: string`                | `void`    |\n| `isCrispPushNotification(data)`                     | Check if a notification payload is from Crisp.                                    | `data: Record\u003cstring, string\u003e` | `boolean` |\n| `setShouldPromptForNotificationPermission(enabled)` | Control auto-prompting for notification permissions (iOS only, no-op on Android). | `enabled: boolean`             | `void`    |\n\n### Message Methods\n\n| Method                 | Description                                         | Parameters                | Return |\n| ---------------------- | --------------------------------------------------- | ------------------------- | ------ |\n| `showMessage(content)` | Display a message as operator in the local chatbox. | `content: MessageContent` | `void` |\n\n### React Hook\n\n| Hook                        | Description                                     | Parameters                       | Return |\n| --------------------------- | ----------------------------------------------- | -------------------------------- | ------ |\n| `useCrispEvents(callbacks)` | Subscribe to SDK events with automatic cleanup. | `callbacks: CrispEventCallbacks` | `void` |\n\n### Utility Functions\n\n| Function          | Description                                    | Parameters | Return   |\n| ----------------- | ---------------------------------------------- | ---------- | -------- |\n| `getSDKVersion()` | Get the crisp-sdk-react-native version string. | -          | `string` |\n\n---\n\n## TypeScript Types\n\n### Core Interfaces\n\n#### Company\n\n```typescript\ninterface Company {\n  name: string; // Required: Company name\n  url?: string; // Company website URL\n  companyDescription?: string; // Brief company description\n  employment?: Employment; // User's job details\n  geolocation?: Geolocation; // Company location\n}\n```\n\n#### Employment\n\n```typescript\ninterface Employment {\n  title?: string; // Job title (e.g., \"Software Engineer\")\n  role?: string; // Department/role (e.g., \"Engineering\")\n}\n```\n\n#### Geolocation\n\n```typescript\ninterface Geolocation {\n  country?: string; // Country name or ISO code\n  city?: string; // City name\n}\n```\n\n#### SessionEvent\n\n```typescript\ninterface SessionEvent {\n  name: string; // Event name\n  color: CrispSessionEventColors; // Event color\n}\n```\n\n### Message Types\n\n#### CrispMessage\n\n```typescript\ninterface CrispMessage {\n  content: string; // Message text\n  timestamp: number; // Unix timestamp (ms)\n  fromOperator: boolean; // true if from operator\n  fingerprint: string; // Unique message ID\n  isMe: boolean; // true if sent by current user\n  origin: CrispMessageOrigin; // \"local\" | \"network\" | \"update\"\n  user?: CrispUser; // Sender information\n}\n```\n\n#### CrispUser\n\n```typescript\ninterface CrispUser {\n  nickname?: string; // Display name\n  userId?: string; // Unique identifier\n  avatar?: string; // Avatar URL\n}\n```\n\n### Message Content Types\n\nThe `showMessage` method accepts these content types:\n\n#### TextMessageContent\n\n```typescript\n{ type: \"text\", text: string }\n```\n\n#### FileMessageContent\n\n```typescript\n{ type: \"file\", url: string, name: string, mimeType: string }\n```\n\n#### AnimationMessageContent\n\n```typescript\n{ type: \"animation\", url: string, mimeType: string }\n```\n\n#### AudioMessageContent\n\n```typescript\n{ type: \"audio\", url: string, mimeType: string, duration: number }\n```\n\n#### PickerMessageContent\n\n```typescript\n{\n  type: \"picker\",\n  id: string,\n  text: string,\n  choices: Array\u003c{ value: string, label: string, selected?: boolean }\u003e\n}\n```\n\n#### FieldMessageContent\n\n```typescript\n{ type: \"field\", id: string, text: string, explain?: string, required?: boolean }\n```\n\n#### CarouselMessageContent\n\n```typescript\n{\n  type: \"carousel\",\n  text: string,\n  targets: Array\u003c{\n    title: string,\n    description?: string,\n    imageUrl?: string,\n    actionUrl?: string\n  }\u003e\n}\n```\n\n### Event Callbacks\n\n```typescript\ninterface CrispEventCallbacks {\n  onSessionLoaded?: (sessionId: string) =\u003e void;\n  onChatOpened?: () =\u003e void;\n  onChatClosed?: () =\u003e void;\n  onMessageSent?: (message: CrispMessage) =\u003e void;\n  onMessageReceived?: (message: CrispMessage) =\u003e void;\n  onPushNotificationReceived?: (notification: PushNotificationPayload) =\u003e void; // iOS only\n  onLogReceived?: (log: CrispLogEntry) =\u003e void;\n}\n```\n\n### Event Payload Types\n\nThese types are used internally by the event system:\n\n```typescript\n// Payload for onSessionLoaded callback\ninterface SessionLoadedPayload {\n  sessionId: string;\n}\n\n// Payload for onMessageSent and onMessageReceived callbacks\ninterface MessagePayload {\n  message: CrispMessage;\n}\n\n// Empty payload for onChatOpened and onChatClosed callbacks\ntype EmptyPayload = Record\u003cstring, never\u003e;\n\n// Payload for onPushNotificationReceived callback (iOS only)\ninterface PushNotificationPayload {\n  title: string;\n  body: string;\n}\n\n// Payload for onLogReceived callback\ninterface LogReceivedPayload {\n  log: CrispLogEntry;\n}\n\n// Log entry from the native SDK\ninterface CrispLogEntry {\n  level: CrispLogLevel; // The log level\n  tag: string; // Log category/source\n  message: string; // Log message content\n}\n\n// Message origin type\ntype CrispMessageOrigin = \"local\" | \"network\" | \"update\";\n```\n\n### Helper Types\n\nTypes used within message content interfaces:\n\n```typescript\n// Choice option for picker messages\ninterface PickerChoice {\n  value: string; // Unique identifier\n  label: string; // Display text\n  selected?: boolean; // Pre-selected state\n}\n\n// Target item for carousel messages\ninterface CarouselTarget {\n  title: string; // Item title\n  description?: string; // Item description\n  imageUrl?: string; // Image URL\n  actionUrl?: string; // Action URL when tapped\n}\n```\n\n### Enums\n\n#### CrispSessionEventColors\n\n| Value        | Color  | Suggested Use                        |\n| ------------ | ------ | ------------------------------------ |\n| `RED` (0)    | Red    | Errors, failures, critical events    |\n| `ORANGE` (1) | Orange | Warnings, attention needed           |\n| `YELLOW` (2) | Yellow | Informational highlights             |\n| `GREEN` (3)  | Green  | Success, completion, positive events |\n| `BLUE` (4)   | Blue   | Informational, neutral events        |\n| `PURPLE` (5) | Purple | Special, premium-related events      |\n| `PINK` (6)   | Pink   | Social, engagement events            |\n| `BROWN` (7)  | Brown  | Historical, archive events           |\n| `GREY` (8)   | Grey   | Secondary, low-priority events       |\n| `BLACK` (9)  | Black  | System, administrative events        |\n\n#### CrispLogLevel\n\n| Value         | Description                             |\n| ------------- | --------------------------------------- |\n| `VERBOSE` (0) | Most verbose; includes all log messages |\n| `DEBUG` (1)   | Debug information for development       |\n| `INFO` (2)    | Informational messages                  |\n| `WARN` (3)    | Warnings (default level)                |\n| `ERROR` (4)   | Error messages only                     |\n| `ASSERT` (5)  | Critical assertion failures             |\n\n---\n\n## Troubleshooting\n\n### \"Expo Go is not supported\"\n\nThe Crisp SDK requires native modules. Use a development build instead:\n\n```bash\nnpx expo run:ios\n# or\nnpx expo run:android\n```\n\n### Chat not appearing after `show()`\n\nEnsure you've called `configure()` with a valid Website ID before calling `show()`.\n\n### Push notifications not working\n\n1. Verify the config plugin is properly configured in `app.json`\n2. Rebuild with `npx expo prebuild --clean`\n3. Ensure your Crisp dashboard has push notifications enabled\n4. For iOS: Verify APNs certificates are configured in Crisp dashboard\n5. For Android: Verify Firebase is properly configured\n\n### Session data not persisting\n\nUse `setTokenId()` with a unique user identifier to enable session persistence across app reinstalls and devices.\n\n---\n\n## Example Apps\n\nTwo fully functional example apps are included in the repository to help you get started:\n\n| App                   | Directory                         | Description                                                                                                                 |\n| --------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| **Expo**              | [`/example`](./example)           | Expo Router app with push notifications (coexistence mode with `expo-notifications`), event listeners, and all SDK features |\n| **Bare React Native** | [`/bare-example`](./bare-example) | Bare React Native CLI app demonstrating integration without the Expo managed workflow                                       |\n\nBoth apps are pre-configured and ready to run — just add your Website ID and follow the setup instructions in each directory.\n\n---\n\n## Resources\n\n- [Crisp SDK Overview](https://crisp.chat/en/sdk/) — All available Crisp SDKs\n- [React Native SDK Page](https://crisp.chat/en/sdk/react-native/) — Product page for this SDK\n- [Crisp Help Center](https://help.crisp.chat/)\n- [Crisp Developer Documentation](https://docs.crisp.chat/)\n- [iOS SDK Documentation](https://docs.crisp.chat/guides/chatbox-sdks/ios-sdk/)\n- [Android SDK Documentation](https://docs.crisp.chat/guides/chatbox-sdks/android-sdk/)\n\n## Contributing\n\nIssues and pull requests are welcome on [GitHub](https://github.com/crisp-im/crisp-sdk-react-native/issues).\n\n## License\n\nMIT - See [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrisp-im%2Fcrisp-sdk-react-native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrisp-im%2Fcrisp-sdk-react-native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrisp-im%2Fcrisp-sdk-react-native/lists"}