@regantis-sdk/react-native-chat

Native Regantis customer-support live chat for React Native Android and iOS. It uses the same Regantis Chat conversations, chatbot, operators, translations, settings and realtime WebSocket infrastructure as the web widget, rendered as a native full-page experience.

Compatibility

• React Native 0.77+
• Android API 24+
• iOS 15.1+
• React Native New Architecture / interoperability-compatible applications
• No runtime npm dependencies other than react and react-native

Install

npm install @regantis-sdk/react-native-chat

Android is autolinked by React Native.

For iOS:

cd ios
pod install
cd ..

Do not place the component inside a ScrollView; the SDK owns its message list, keyboard handling and scrolling. Give its parent a bounded/full-screen height, normally flex: 1.

Basic usage

Create or edit the Chat integration in the Regantis CRM and copy its React Native API key.

import React from 'react';
import { View } from 'react-native';
import { RegantisChat } from '@regantis-sdk/react-native-chat';

export default function SupportScreen() {
  return (
    <View style={{ flex: 1 }}>
      <RegantisChat apiKey="YOUR_REACT_NATIVE_CHAT_API_KEY" />
    </View>
  );
}

The SDK downloads the current Chat settings and UI texts from the CRM. Colors, logo, agent display, sounds, ratings, transcript, translation options and white-label settings therefore remain centrally managed instead of being duplicated in every mobile app.

Full-page navigation

The default native flow mirrors the mobile web widget: Welcome/Home → Chat.

<RegantisChat
  apiKey="YOUR_REACT_NATIVE_CHAT_API_KEY"
  initialView="home"
  onBack={() => navigation.goBack()}
  onClose={() => navigation.goBack()}
  onViewChange={view => {
    // "home" or "chat"
  }}
/>

Use initialView="chat" to enter the conversation directly.

onBack handles the top-left back action on the Welcome screen. onClose handles the widget-style minimize/close navigation action when supplied by the host app.

If your app has its own fixed header, use keyboardVerticalOffset when necessary:

<RegantisChat
  apiKey="YOUR_REACT_NATIVE_CHAT_API_KEY"
  keyboardVerticalOffset={64}
/>

Logged-in customers

A logged-in application customer can be passed to Chat so the SDK skips the public contact form and the CRM can reliably associate the conversation with that customer.

Never put the customer identity signing secret in the React Native app. Generate the HMAC on your authenticated application backend.

The signed payload is:

timestamp
customer_id
name
lowercase_email
telephone

Sign that exact string with HMAC-SHA256 using the Chat customer identity signing secret from the CRM. The timestamp is a Unix timestamp in seconds. The current CRM validation window is 10 minutes.

Static example:

<RegantisChat
  apiKey="YOUR_REACT_NATIVE_CHAT_API_KEY"
  customer={{
    id: user.id,
    name: user.name,
    email: user.email,
    telephone: user.telephone,
    identityTimestamp: chatIdentity.timestamp,
    identitySignature: chatIdentity.signature,
  }}
/>

For real applications, prefer customerProvider. It lets the SDK obtain a fresh short-lived identity on startup and when the application returns to the foreground:

<RegantisChat
  apiKey="YOUR_REACT_NATIVE_CHAT_API_KEY"
  customerProvider={async () => {
    const response = await yourAuthenticatedApi.get('/chat-identity');

    if (!response.data.logged) {
      return null;
    }

    return {
      id: response.data.customer_id,
      name: response.data.name,
      email: response.data.email,
      telephone: response.data.telephone,
      identityTimestamp: response.data.chat_identity.timestamp,
      identitySignature: response.data.chat_identity.signature,
    };
  }}
/>

The SDK handles live identity changes. Anonymous → login can upgrade the current visitor conversation to the verified customer. Logout and account switching start a fresh visitor session so a signed customer's conversation is never reused by another customer or by an anonymous visitor. For defense in depth, deploy the matching Chat 1.0 CRM server hardening patch as well.

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | apiKey | string | required | 64-character React Native Chat API key from the CRM. | | serverUrl | string | Regantis CRM URL | Override only when using another Regantis CRM host. | | language | string | en | UI language. Server-supported UI languages currently include en, ro, de, fr, es, it. | | translationLanguage | string | '' | Initial customer translation language when customer translation is enabled. | | customer | object | null | Optional signed logged-in customer. | | customerProvider | function | null | Async/sync provider for a fresh signed customer identity. Recommended for authenticated apps. | | theme | object | CRM settings | Optional per-app setting/color overrides. | | texts | object | CRM texts | Optional per-app localized text overrides. | | screen | string | chat | Host-app screen/context identifier sent with visitor context. | | initialView | home \| chat | home | Initial native screen. | | style | React Native style | — | Style applied to the SDK root. | | keyboardVerticalOffset | number | 0 | Offset passed to the iOS KeyboardAvoidingView. | | onBack | function | — | Welcome-screen back action. | | onClose | function | — | Host navigation/minimize action. | | onViewChange | function | — | Called with home or chat. | | onMessage | function | — | Called for new support/chatbot messages received by the SDK. | | onUnreadChange | function | — | Called when the SDK unread count changes. | | onError | function | — | Receives transport/native SDK errors. |

TypeScript declarations are included with the package.

Optional settings/text overrides

CRM configuration remains authoritative. Override only what a specific application needs:

<RegantisChat
  apiKey="YOUR_REACT_NATIVE_CHAT_API_KEY"
  language="ro"
  translationLanguage="de"
  theme={{
    theme_mode: 'dark',
    primary_color: '#0B63E5',
  }}
  texts={{
    placeholder: 'Scrie un mesaj…',
  }}
/>

Included functionality

• native Welcome/Home and Chat screens matching the mobile web-widget flow
• persistent anonymous visitor/session identity
• signed logged-in customer identity with live login/logout/account-switch handling
• contact form and verified-customer flow
• conversation restore and missed-message recovery
• message history with older-history pagination
• send/receive messages
• chatbot replies and chatbot → operator handoff
• WebSocket realtime updates with HTTP polling fallback
• typing state and visitor read state
• foreground/background lifecycle recovery and WebSocket/token refresh
• customer translation selector
• direct camera capture
• image/gallery picker
• file picker
• image uploads and file uploads
• fullscreen image lightbox with pinch/pan and −, 1:1, + zoom controls
• native incoming-message sound with persisted user preference
• close/reopen conversation
• rating and rating comment
• transcript delivery to a valid recipient email
• light/dark themes
• standard and advanced Chat colors/background opacity
• configurable logo, agent photo, operator/profile names and white-label mode
• CRM-managed localized texts

Android

The SDK declares its camera permission and FileProvider through manifest merging. Camera permission is requested only when the user chooses Take photo.

No storage permission is required for the system gallery/file picker flow.

No manual React Native package registration is required when autolinking is enabled.

iOS

After installation:

cd ios
pod install
cd ..

For camera capture, add this to the host application's Info.plist:

<key>NSCameraUsageDescription</key>
<string>Take photos to attach to support chat messages.</string>

The system file/image picker does not require a broad photo-library permission for the current SDK flow.

Realtime and app lifecycle

The SDK uses the existing signed Regantis Chat WebSocket connection while the app is active. If realtime is temporarily unavailable, HTTP polling continues as a fallback.

When the app backgrounds, the SDK pauses the active realtime/polling work. On foreground it refreshes customer identity when a provider is configured, refreshes the session/tokens, synchronizes missed messages and reconnects realtime.

Background/terminated-app push notifications are not part of this package yet. They will be delivered through the separate Regantis Push integration when enabled; the Chat SDK does not embed a second FCM/APNs provider.

Transcript protection

The visitor can request a transcript for any valid recipient email. The CRM backend applies its transcript verification flow where required and enforces a dedicated anti-spam limit of 5 transcript requests per IP, per Chat, per day, in addition to normal API rate limits.

Native settings vs web-only settings

Portable Chat settings are honored in the native page, including themes/colors, branding, agent display, sounds, ratings, transcript, translations and texts.

These web-loader settings are intentionally not applied to a full-page native screen:

• desktop/mobile corner alignment
• launcher side/bottom spacing
• launcher visibility rules
• minimized bubble / bar launcher style
• before_you_go_enabled desktop mouse-exit prompt

They can remain configured in CRM because the same Chat integration may also be used on the web.

Headless client

Apps that need a completely custom UI can use the same transport/session client directly:

import { createRegantisChatClient } from '@regantis-sdk/react-native-chat';

const chat = createRegantisChatClient({
  apiKey: 'YOUR_REACT_NATIVE_CHAT_API_KEY',
  language: 'ro',
});

const unsubscribe = chat.subscribe(state => {
  // Render state.messages, state.conversation, state.unread, etc.
});

await chat.start();
await chat.sendMessage('Salut');

unsubscribe();
chat.stop();

The headless client also exposes contact, history, attachments, translation, transcript, rating, close/reopen, lifecycle and read-state methods. See the bundled TypeScript declarations for the complete API.

Troubleshooting

INVALID_SERVER_RESPONSE_200

The SDK expected JSON but received another HTTP 200 response, commonly an HTML login/fallback page. Verify that the CRM chat/widget/sdkConfig clean URL exists and that the SDK widget routes are public visitor routes rather than CRM-login-protected routes.

SDK_FORBIDDEN

The React Native API key is invalid, revoked, belongs to a disabled Chat integration, or the wrong key type was supplied. Use the React Native API key, not the web widget key.

Camera does not open

On Android, grant camera permission when requested. If permission was permanently denied, use the SDK's Open settings action.

On iOS, verify NSCameraUsageDescription exists in the host Info.plist and rebuild the native application after changing it.

UPLOAD_UNAVAILABLE

Uploads require an active confirmed conversation and a valid short-lived upload token. Complete the contact/verified-customer step and ensure the conversation is open.

UI does not fill the page

Use a flex: 1 parent and do not wrap RegantisChat in another ScrollView.

Security notes

• The React Native SDK key is separate from the web widget key and can be independently revoked.
• Never ship the customer identity signing secret in JavaScript, Android resources or the IPA/APK.
• Signed customer identity is generated only by the host application's trusted backend.
• The CRM validates signed customer identity and isolates trusted conversations across logout/account changes.
• Realtime and upload access use short-lived signed tokens issued by the Chat backend.