@zowieteam/chat-react-native-sdk

Zowie chat as a React Native component. Drop <ZowieChat> into your app, give it your baseUrl and instanceId, and it renders the full Zowie chat experience — messaging, voice, file upload/download, visual aids and CSAT — with configuration and session handling built in.

Features

• Full feature parity with the Zowie web widget (text + voice, file upload, transcript download, visual aids, CSAT).
• Automatic configuration fetching and session persistence.
• Imperative API (send messages, start/end chat, update user attributes) via a ref.
• Rich event callbacks (messages, lifecycle, unread count, downloads, links).
• Declares no device permissions on your behalf — you add only what you use.

Requirements

• React Native 0.78+ with the New Architecture enabled.
• iOS deployment target 15.6+.
• Peer dependencies your app must have installed: react, react-native, and react-native-webview (>= 13).

The SDK also pulls in react-native-blob-util (file download) and react-native-keychain (session storage) as autolinked native modules — run pod install after installing.

Installation

npm install @zowieteam/chat-react-native-sdk
# or
yarn add @zowieteam/chat-react-native-sdk

cd ios && pod install

Quick start

import { ZowieChat } from '@zowieteam/chat-react-native-sdk';
import { SafeAreaView } from 'react-native';

export function ChatScreen() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <ZowieChat
        baseUrl="https://<slug>.chat.getzowie.com"
        instanceId="<your-instance-id>"
        style={{ flex: 1 }}
      />
    </SafeAreaView>
  );
}

<ZowieChat> fetches its configuration, restores any persisted session, and starts the conversation automatically — baseUrl and instanceId are the only required props.

Props

Required

| Prop | Type | Description | | ------------ | -------- | ------------------------------------------------------------------------ | | baseUrl | string | Base origin of your Zowie deployment, e.g. https://<slug>.chat.getzowie.com. | | instanceId | string | Zowie chatbot instance ID. |

Configuration

| Prop | Type | Description | | ------------------------- | ------------------ | ----------------------------------------------------------------- | | style | StyleProp<ViewStyle> | Layout/sizing for the chat (e.g. { flex: 1 }). | | metadata | Metadata | User attributes. metadata.locale also selects the bot's region. | | externalAccessToken | string | JWT for authenticated (logged-in) sessions; anonymous when omitted. | | context | string | Custom context string passed to the bot. | | resetSession | boolean | Clear any persisted session on init. | | initialConversationMode | 'text' \| 'voice'| Mode the chat opens in (default text). | | referral | string | Referral used for auto-start (default "start"). | | initialUserMessage | string | Initial user message sent with auto-start. |

Branding

| Prop | Type | Description | | ----------------------- | ------------------- | ------------------------------------------------ | | title | string | Header title. | | primaryColor | string | Primary color (applied to both light and dark). | | fontColor | 'white' \| 'black'| Font color (applied to both light and dark). | | logoUrl | string | Logo shown in the chat header. | | voiceExperienceEnabled| boolean | Enable voice conversation mode. | | voiceBlobColor | string | Color of the voice visualization. |

Events

| Prop | Signature | Fires when… | | ------------------- | -------------------------------------- | ------------------------------------------------------- | | onLoaded | () => void | The chat finished loading. | | onStartChat | (conversationId: string) => void | A conversation started. | | onEndChat | () => void | The conversation ended. | | onMessageSent | (message: string) => void | The user sent a message. | | onMessageReceived | (payload: unknown) => void | A message was received. | | onSessionExpired | () => void | The session expired. | | onUnreadMessages | (count: number) => void | The unread message count changed. | | onMinimize | () => void | The user tapped the minimize control. | | onLinkClicked | (url: string) => void | A link in the chat was opened. | | onLinkPress | (url: string) => boolean | Override link opening — return true if handled. | | onDownload | (file: ChatDownload) => void | Override download handling (default: save & share via OS). | | onAndroidBackPress| () => boolean | Android hardware back — return true to consume. | | onConfigError | (error: unknown) => void | Loading the chat configuration failed. | | on | (eventName: string, params: string) => void | Generic backend event subscription (Decision Engine). |

Imperative API

Pass a ref to call methods on the chat directly:

import { useRef } from 'react';
import { ZowieChat, type ZowieChatHandle } from '@zowieteam/chat-react-native-sdk';

function Example() {
  const chat = useRef<ZowieChatHandle>(null);

  // chat.current?.sendMessage('Hello');

  return <ZowieChat ref={chat} baseUrl="…" instanceId="…" style={{ flex: 1 }} />;
}

| Method | Signature | Description | | ------------------- | ---------------------------------- | ----------------------------------------------------------------- | | sendMessage | (message: string) => void | Send a message as the user. | | sendReferral | (referralId: string) => void | Send a referral / campaign ID to the conversation. | | updateMetadata | (metadata: Metadata) => void | Update the user attributes. | | setVisible | (visible: boolean) => void | Set whether the chat is visible. | | showCsat | () => void | Show the customer satisfaction survey. | | startChat | () => void | Start a new conversation when none is active (no-op otherwise). | | endChat | () => void | Clear the stored session and current conversation (use on logout). | | getConversationId | () => string \| undefined | The active conversation's ID, or undefined when none is open. |

Types

The exported types referenced by the props and callbacks above:

Metadata

User attributes passed via the metadata prop or updateMetadata. All fields are optional.

| Field | Type | Description | | ------------- | ------------------------ | ----------------------------------------------------- | | firstName | string | User's first name. | | lastName | string | User's last name. | | name | string | Full display name. | | email | string | User's email address. | | phoneNumber | string | User's phone number. | | locale | string | Locale, e.g. en-US. Also selects the bot's region. | | timezone | string | IANA timezone, e.g. Europe/Warsaw. | | extraParams | Record<string, string> | Arbitrary custom attributes sent alongside the rest. |

ChatDownload

Passed to onDownload when a file download is triggered inside the chat. Exactly one of base64 or url is set.

| Field | Type | Description | | ---------- | -------- | ------------------------------------------------------------ | | filename | string | Suggested file name. | | mimeType | string | MIME type, when known. | | base64 | string | Base64 contents, for client-generated files (e.g. transcript). | | url | string | Direct download URL. |

Permissions

The SDK does not declare any device permissions on your behalf — so apps that don't use voice or photo upload aren't forced to request the microphone or camera (which would otherwise show up in store listings and review). If you enable those features, declare the permissions in your own app.

Voice (microphone)

Android — add to your AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

Both are required for voice. RECORD_AUDIO is a runtime permission and is requested automatically on first use.

iOS — add to your Info.plist (required for microphone access):

<key>NSMicrophoneUsageDescription</key>
<string>The microphone is used for voice conversations in the chat.</string>

Photo upload (camera)

Only needed if users take photos via the in-chat file picker.

iOS — Info.plist:

<key>NSCameraUsageDescription</key>
<string>The camera is used to take and send photos in the chat.</string>

(Choosing existing photos uses the system picker and needs no permission. On Android the system file/camera picker handles its own permissions.)

License

MIT