SDK & Widget · Mobile

React Native SDK

The @inboxi/react-native-chat package gives you a complete chat screen and a small client for sessions, identity, history and push.

The SDK handles the session token, persists it between launches, opens the Socket.IO connection, falls back to REST when the socket is down, and renders a themed chat UI. You call three methods and render one component.

InboxiChat.init()

Once, at app start

InboxiChat.identify()

After your user logs in

Your support screen

setDeviceToken()

Optional, for push

Install

bash

npm install @inboxi/react-native-chat socket.io-client @react-native-async-storage/async-storage

Requirement	Version
react	>= 17.0.0
react-native	>= 0.65
socket.io-client	>= 4.0
@react-native-async-storage/async-storage	>= 1.17

1. Initialize

Call init once when the app starts, before rendering the chat. Pass AsyncStorage so the session survives restarts.

App.js

import AsyncStorage from '@react-native-async-storage/async-storage';
import { InboxiChat } from '@inboxi/react-native-chat';

const { config, visitorId, restored } = await InboxiChat.init({
  appId: 'YOUR_APP_ID',          // Settings › Developer Hub › Credentials & Setup
  apiKey: 'YOUR_API_KEY',        // Settings › Developer Hub › API Keys
  asyncStorage: AsyncStorage,    // persists the session between launches
  // baseUrl: 'https://inboxi.app' (default)
});

When a saved session is found and still valid, init reuses it and returns restored: true; otherwise it opens a new session. config holds the widget look from your dashboard (colors, welcome message, business name, logo, language).

2. Identify the user

After your user signs in, tell Inboxi who they are. name is required.

javascript

const { visitorId, chatId, isNewChat } = await InboxiChat.identify({
  id: user.id,
  name: user.name,
  email: user.email,
  phone: user.phone,
  data: { plan: 'premium', city: 'Cairo' }, // optional custom fields
});

The visitor identity is fixed when the session opens. A user saved by a previous identify call is reused as the visitor ID on the next init, so a returning user keeps their history. If a different person signs in on the same device, call logout() and then init() before identifying them.

3. Show the chat screen

SupportScreen.js

import { ChatScreen } from '@inboxi/react-native-chat';

export default function SupportScreen({ navigation }) {
  return (
    <ChatScreen
      onClose={() => navigation.goBack()}
      onNewMessage={(msg) => console.log('Agent replied:', msg.content)}
      theme={{ primaryColor: '#6366f1', headerTitle: 'Support' }}
    />
  );
}

ChatScreen connects the socket when it mounts and disconnects when it unmounts, loads the conversation history, shows a welcome state for new chats, sends with an optimistic bubble, and shows "agent joined" and "chat resolved" notices. The input placeholder switches to Arabic when the widget language is ar.

Prop	Type	Required	Description
`theme`	object	optional	Visual overrides, see Theming below.
`onClose`	function	optional	Called when the user taps the close button in the header.
`onNewMessage`	function(message)	optional	Called for each reply from your team or AI, with { id, content, senderName, … }.
`style`	ViewStyle	optional	Extra styles for the outer container.

4. Push notifications (optional)

javascript

import { Platform } from 'react-native';
import messaging from '@react-native-firebase/messaging';

const token = await messaging().getToken();
await InboxiChat.setDeviceToken(token, Platform.OS); // 'ios' | 'android'

Configure your FCM / APNs credentials first; see Push notifications.

5. Log out

javascript

await InboxiChat.logout(); // clears the session, the saved user and all listeners

InboxiChat API

Every method except the getters throws Call InboxiChat.init() first when used before init.

Method	Returns	Description
`init({ appId, apiKey, baseUrl?, asyncStorage? })`	`{ config, visitorId, restored }`	Opens or restores a session. Throws if appId or apiKey is missing.
`identify({ id, name, email?, phone?, data? })`	`{ visitorId, chatId, isNewChat }`	Attaches user details; name is required.
`setDeviceToken(token, platform)`	`{ deviceTokenId, isNew }`	Registers an FCM / APNs token. platform is 'ios' or 'android'.
`sendMessage(text)`	`{ messageId, chatId, timestamp }`	Sends a message over REST (no socket needed).
`getMessages(chatId, { page?, limit? })`	`{ messages, pagination }`	Message history, oldest first. Default 50 per page.
`getConversations()`	`{ conversations }`	The visitor's conversations, newest first.
`onMessage(callback)`	unsubscribe()	Listens for replies delivered to a mounted ChatScreen.
`logout()`	Promise	Clears token, user, config and listeners from memory and storage.
`isInitialized()`	boolean	Whether a session is active.
`getConfig()`	object	Widget config returned by init (colors, welcome message…).
`getVisitorId() · getUser() · getOrganizationId()`	value	Current visitor ID, identified user, workspace ID.
`getBaseUrl() · getSessionToken()`	string	Useful when you call the REST API or socket yourself.

Theming

By default the screen uses the colors from your widget settings. Anything you pass in theme wins over the dashboard value.

theme key	Affects	Falls back to
`primaryColor`	Your visitor's bubbles, send button, loading spinner	Widget primary color, then #6366f1
`headerColor`	Header background	Widget header color, then primary color
`headerTextColor`	Header text and icons	Widget header text color, then white
`headerTitle`	Header title	Business name, then "Support"
`backgroundColor`	Message list background	Widget chat background, then #f0f2f5

Build your own UI

The building blocks behind ChatScreen are exported too:

javascript

import {
  ChatHeader,     // ({ config, theme, isConnected, onClose })
  MessageBubble,  // ({ message, config, theme })
  MessageInput,   // ({ onSend, placeholder, config, theme, disabled })
  useSocket,      // → { isConnected, connect, disconnect, on, emit, sendMessage }
  useMessages,    // (socketHook) → { messages, chatId, loading, send, loadHistory, addMessage }
} from '@inboxi/react-native-chat';

useMessages(useSocket()) gives you the same behavior as the stock screen: history on join, de-duplicated live replies, and send(text) that tries the socket first and falls back to REST.