React Native SDK

The @chatropic/react-native package renders a native chat UI that loads its branding and copy from your Mobile app deploy profile. The SDK connects to the Chatropic production host automatically, so there is no API host to configure. The SDK is currently Betaits branding and copy from your Mobile app deploy profile. The SDK connects to the Chatropic production host automatically, so there is no API host to configure. The SDK is currently Beta.

Prerequisites

Deploy the Mobile app profile: open Deploy > Mobile app, click Deploy, and confirm the profile showsDeploy the Mobile app profile: open Deploy > Mobile app, click Deploy, and confirm the profile shows Live.
Copy your publishable key from the Embed tab on Deploy >Copy your publishable key from the Embed tab on Deploy > Mobile app.

Install

npm install @chatropic/react-native

Peer dependencies are react >= 18 and react-native >= 0.73. Optional packages unlock extra featuresPeer dependencies are react >= 18 and react-native >= 0.73. Optional packages unlock extra features:

Package	Enables
`@react-native-async-storage/async-storage`	Local chat history via `createChatStorage`
`expo-audio` and `expo-file-system`	Voice
`expo-linear-gradient`	Gradient accents
`react-native-safe-area-context`	Native safe-area handling
`react-native-svg`	The Chatropic mark and inline icons

Package	Enables
`@react-native-async-storage/async-storage`	Local chat history via `createChatStorage`
`expo-audio` and `expo-file-system`	Voice
`expo-linear-gradient`	Gradient accents
`react-native-safe-area-context`	Native safe-area handling
`react-native-svg`	The Chatropic mark and inline icons

Floating launcher

The launcher renders a floating button that opens the chat panel, matching the web widget experience:

import { ChatWidgetLauncher } from "@chatropic/react-native";

<ChatWidgetLauncher
  publishableKey="cpk_live_..."
  onNavigate={(path) => router.push(path)}
/>

Full-screen chat

The launcher renders a floating button that opens the chat panel, matching the web widget experience:

import { ChatWidgetLauncher } from "@chatropic/react-native";

<ChatWidgetLauncher
  publishableKey="cpk_live_..."
  onNavigate={(path) => router.push(path)}
/>

Full-screen chat

Use ChatWidgetScreen for a dedicated support screen in your navigation stack:Use ChatWidgetScreen for a dedicated support screen in your navigation stack:

import { ChatWidgetScreen } from "@chatropic/react-native";

<ChatWidgetScreen
  publishableKey="cpk_live_..."
  onNavigate={(path) => router.push(path)}
  onBack={() => navigation.goBack()}
/>

import { ChatWidgetScreen } from "@chatropic/react-native";

<ChatWidgetScreen
  publishableKey="cpk_live_..."
  onNavigate={(path) => router.push(path)}
  onBack={() => navigation.goBack()}
/>

Both components default to the mobile deploy profile when profile is omittedBoth components default to the mobile deploy profile when profile is omitted.

Pass signed-in user details

When your app knows who is logged in, pass user props on both ChatWidgetLauncher and ChatWidgetScreen so actions, inbox routing, and chat logs resolve to the correct person:

const displayName = user
  ? `${user.first_name} ${user.last_name}`.trim()
  : undefined;

<ChatWidgetLauncher
  publishableKey={publishableKey}
  endUserId={user.id}
  userName={displayName}
  userEmail={user.email}
  onNavigate={handleNavigate}
/>

Prop	Required	Purpose
`endUserId`	For authenticated actions	Stable user id that becomes `{{end_user_id}}` in action headers
`userName`	Optional	Display name in Inbox and Slack escalation alerts
`userEmail`	Optional	Email shown alongside the name in Inbox and alerts

For production apps, also pass a backend-signed identityToken so a modified client cannot impersonate another user. See Authentication & identity.

Pass signed-in user details

When your app knows who is logged in, pass user props on both ChatWidgetLauncher and ChatWidgetScreen so actions, inbox routing, and chat logs resolve to the correct person:

const displayName = user
  ? `${user.first_name} ${user.last_name}`.trim()
  : undefined;

<ChatWidgetLauncher
  publishableKey={publishableKey}
  endUserId={user.id}
  userName={displayName}
  userEmail={user.email}
  onNavigate={handleNavigate}
/>

Prop	Required	Purpose
`endUserId`	For authenticated actions	Stable user id that becomes `{{end_user_id}}` in action headers
`userName`	Optional	Display name in Inbox and Slack escalation alerts
`userEmail`	Optional	Email shown alongside the name in Inbox and alerts

For production apps, also pass a backend-signed identityToken so a modified client cannot impersonate another user. See Authentication & identity.

Agent BFF (recommended for signed-in apps)

If your API actions call your backend rather than a third-party OAuth providerrather than a third-party OAuth provider, use a static BFF token plus endUserId:

In Actions > Manage tokens, create a New token with type Static value (for exampleIn Actions > Manage tokens, create a New token with type Static value (for example my_bff).
Point actions at your backend with Authorization: Bearer {{token.my_bff}} and X-End-User-Id: {{end_user_id}} headersbackend with Authorization: Bearer {{token.my_bff}} and X-End-User-Id: {{end_user_id}} headers.
Mount the widget with endUserId={user.id}.

See Manage tokens and the Pricepally ecommerce recipe for a worked exampl and the Pricepally ecommerce recipe for a worked example.

Configurationonfiguration

The SDK fetches your deployed widget configuration at startup. Applied fields include the display name, welcome message, suggested prompts, colors, theme, logo, and privacy notice. Model settings and agent instructions stay server-sideThe SDK fetches your deployed widget configuration at startup. Applied fields include the display name, welcome message, suggested prompts, colors, theme, logo, and privacy notice. Model settings and agent instructions stay server-side.

All props

Prop	Purpose
`publishableKey`	Publishable key from Deploy > Mobile app > Embed
`profile`	Deploy profile to load; defaults to the mobile profile
`sessionId`	Pin a specific conversation session
`endUserId`	Stable signed-in user id
`identityToken`	Backend-signed JWT proving the user id
`userName`	Visitor display name for inbox and alerts
`userEmail`	Visitor email for inbox and alerts
`theme`	Override light or dark appearance
`storage`	Persist the session id and turns locally (`createChatStorage`)
`onNavigate`	Navigation card deeplink handler
`onBack`	Back button handler (`ChatWidgetScreen` only)
`onUserMessage` / `onAgentDone`	Analytics hooks

When the agent returns a navigation card, the SDK calls onNavigate(path) with a relative path from your route registry. Wire it to your navigator:

onNavigate={(path) => {
  if (path === "/billing") navigation.navigate("Billing");
}}

Voice

Voice is optional and requires compatible native audio modules:

npm install expo-audio expo-file-system

Also configure microphone permissions in your iOS and Android projects.

All props

Prop	Purpose
`publishableKey`	Publishable key from Deploy > Mobile app > Embed
`profile`	Deploy profile to load; defaults to the mobile profile
`sessionId`	Pin a specific conversation session
`endUserId`	Stable signed-in user id
`identityToken`	Backend-signed JWT proving the user id
`userName`	Visitor display name for inbox and alerts
`userEmail`	Visitor email for inbox and alerts
`theme`	Override light or dark appearance
`storage`	Persist the session id and turns locally (`createChatStorage`)
`onNavigate`	Navigation card deeplink handler
`onBack`	Back button handler (`ChatWidgetScreen` only)
`onUserMessage` / `onAgentDone`	Analytics hooks

When the agent returns a navigation card, the SDK calls onNavigate(path) with a relative path from your route registry. Wire it to your navigator:

onNavigate={(path) => {
  if (path === "/billing") navigation.navigate("Billing");
}}

Voice

Voice is optional and requires compatible native audio modules:

npm install expo-audio expo-file-system

Also configure microphone permissions in your iOS and Android projects.

Current limitations

No inline embed layout; use the launcher or full-screen chat
Rich widgets other than NavigationCard render a JSON fallback
Voice requires the optional Expo audio packages

Deploy guide

Dashboard-side setup for the Mobile app profile.

Manage tokens

BFF credentials for signed-in apps.

SDK reference

Full prop and helper reference.

Embed navigation

The same navigation payload on the web.

Quick Start

Integration

Navigation Routes

Reference

Prerequisites

Install

Floating launcher

Full-screen chat

Full-screen chat

Pass signed-in user details

Pass signed-in user details

Agent BFF (recommended for signed-in apps)

Configurationonfiguration

All props

Navigation deeplinks

Voice

All props

Navigation deeplinks

Voice

Current limitations

Deploy guide

Manage tokens

SDK reference

Embed navigation

​Prerequisites

​Install

​Floating launcher

​Full-screen chat

​Full-screen chat

​Pass signed-in user details

​Pass signed-in user details

​Agent BFF (recommended for signed-in apps)

​Configurationonfiguration

​All props

​Navigation deeplinks

​Voice

​All props

​Navigation deeplinks

​Voice

​Current limitations

Deploy guide

Manage tokens

SDK reference

Embed navigation

Prerequisites

Install

Floating launcher

Full-screen chat

Full-screen chat

Pass signed-in user details

Pass signed-in user details

Agent BFF (recommended for signed-in apps)

Configurationonfiguration

All props

Navigation deeplinks

Voice

All props

Navigation deeplinks

Voice

Current limitations