@experiaapp/webchat-react-native

@experiaapp/webchat-react-native

A drop-in React Native webchat SDK — real-time chat, media attachments (images, documents, voice notes), and 1:1 video calls — that you embed in your app with a single component. Theming, language (English/Arabic), and behavior are driven by your channel configuration.

• Real-time messaging (text, quick replies, message status, unread tracking)
• Attachments — photos, PDF documents, and recorded voice notes
• In-app video calls (optional)
• Server-driven theming + a customizable launcher
• English / Arabic with full RTL
• Works in Expo and bare React Native

---

Requirements

• React Native >= 0.74, React >= 18
• An Expo-managed / dev-client app, or a bare RN app with Expo Modules (see Bare React Native)
• A channel and connection details from your Experia account

---

Installation

# the SDK
npm install @experiaapp/webchat-react-native

# required peers
npx expo install \
  react-native-safe-area-context \
  react-native-localize \
  @react-native-async-storage/async-storage

Optional peers (each enables a feature when installed)

Install only what you need — the SDK auto-detects them and degrades gracefully when absent:

Feature	Install
Photo / document attachments	npx expo install expo-image-picker expo-document-picker expo-file-system
Voice-note recording & playback	npx expo install expo-audio
Crisp vector icons	npx expo install react-native-svg
Connectivity-aware reconnect	npx expo install @react-native-community/netinfo
Video calls	npx expo install react-native-webrtc react-native-incall-manager

Expo config plugin

Add the plugin to your app.json / app.config.js so the required iOS/Android permissions (camera, microphone, photo library) are injected at build time:

{
  "expo": {
    "plugins": [
      "@experiaapp/webchat-react-native",
      "@config-plugins/react-native-webrtc"   // only if you use video calls
    ]
  }
}

Then create a development build (eas build, or expo prebuild && expo run:ios|run:android) — the chat, media, and video features rely on native modules and won't work in Expo Go.

Bare React Native

The optional Expo peers above need the Expo Modules runtime. In a bare app, run once:

npx install-expo-modules@latest

Then cd ios && pod install and rebuild.

---

Quick start

import React from "react";
import { SafeAreaProvider } from "react-native-safe-area-context";
import { WebChat } from "@experiaapp/webchat-react-native";

const CONFIG = {
  channelId: "YOUR_CHANNEL_ID",
  connectionUrl: "YOUR_SOCKET_HOST",
  configUrl: "YOUR_CONFIG_HOST",
  language: "en", // "en" | "ar"
};

export default function App() {
  return (
    <SafeAreaProvider>
      <WebChat config={CONFIG} />
    </SafeAreaProvider>
  );
}

That's the whole integration: a floating launcher button appears, and tapping it opens the chat. Branding, title, avatar, and theme come from your channel configuration (fetched via configUrl), so you usually only provide the connection details above.

channelId, connectionUrl, and configUrl identify and connect your channel — you receive these with your Experia account.

---

Configuration

The config prop carries your connection details. Everything else — video calls, attachments, the pre-chat form, branding, title, avatar, and colors — is configured in your Experia channel and fetched at runtime via configUrl. In most apps you only pass the connection details (plus, optionally, the language):

<WebChat
  config={{
    channelId: "YOUR_CHANNEL_ID",
    connectionUrl: "YOUR_SOCKET_HOST",
    configUrl: "YOUR_CONFIG_HOST",
    language: "en", // "en" | "ar" — drives RTL (optional)
  }}
/>

Managed in your Experia channel (no app changes)

Controlled from your channel configuration and applied automatically — you don't set these in code:

• Features: video calls, image / document / voice attachments, emoji picker, typing indicator, "powered by" badge
• Launcher & chrome: default launcher visibility, close button, online/offline status, connecting text
• Branding: theme & colors, header title/subtitle, agent avatar, launcher image
• Pre-chat form: enabled, fields (text / email / phone / dropdown), labels, headline, submit label
• Behavior: history-persistence window, welcome message

Advanced — overriding the channel config

Precedence is prop → channel → default, so you can override any setting per build by passing it on config. This is an escape hatch, not the usual path — e.g. force a pre-chat form or turn video off regardless of the channel:

<WebChat
  config={{
    channelId: "YOUR_CHANNEL_ID",
    connectionUrl: "YOUR_SOCKET_HOST",
    configUrl: "YOUR_CONFIG_HOST",
    makeVideoCall: false, // override the channel
    prechatForm: {
      enabled: true,
      fields: [{ key: "name", type: "text", label: { en: "Name", ar: "الاسم" }, required: true }],
    },
  }}
/>

Host-side props

These live on the component, not the channel config:

Prop	Type	Description
config	object	Connection details (+ optional overrides). Required.
open	boolean	Open the surface on mount.
title	string	Override the channel's header title.
renderLauncher	({ open }) => ReactNode	Render your own launcher (see below).
prechatValues	Record<string, string>	Pre-fill the greeting with known user data.
disabledInput	boolean	Lock the composer.
secureScreen	boolean	Block screen capture while the chat is open (best-effort).

Callbacks: onOpen, onClose, onMessageReceived(message), onConnected, onDisconnected, onError(error), onUnreadChange(count).

---

Controlling the chat (imperative API)

Attach a ref to open/close the chat or manage the session from anywhere in your app:

import { useRef } from "react";
import { WebChat, type WebChatHandle } from "@experiaapp/webchat-react-native";

const chat = useRef<WebChatHandle>(null);

<WebChat ref={chat} config={CONFIG} />;

// elsewhere:
chat.current?.open();
chat.current?.close();
chat.current?.sendMessage("Hello");
chat.current?.getUnreadCount();   // number
chat.current?.clearHistory();     // drop messages, keep the session
chat.current?.resetSession();     // start a new session + clear history

clearHistory() / resetSession() erase the locally stored conversation — call one on user logout.

---

Customizing the launcher

The default is a round floating button. You can change it four ways:

1. Your own launcher (any shape):

<WebChat
  config={CONFIG}
  renderLauncher={({ open }) => (
    <Pressable onPress={open} style={{ /* a pill, bar, avatar, anything */ }}>
      <Text>Chat with us</Text>
    </Pressable>
  )}
/>

2. Trigger from your own UI — hide the built-in button and open via the ref:

<WebChat ref={chat} config={{ ...CONFIG, showButtonChat: false }} />
// <YourButton onPress={() => chat.current?.open()} />

3. Reshape the default via channel theme tokens (size, color, corner radius).

4. Use a branded image via the openLauncherImage channel config.

---

Media & video

• Attachments: images (PNG/JPEG), PDF documents, and voice notes. Picking is gated by the uploadMedia / upload* flags; selected files are validated against the channel's allow-list before sending.
• Video calls: set makeVideoCall: true to show the call button (a call can also start automatically when your channel triggers it). Video requires the react-native-webrtc + react-native-incall-manager peers, the @config-plugins/react-native-webrtc Expo plugin (managed apps), and a development build.

Notifications: the SDK does not integrate push. Use the onMessageReceived callback to fire your own local notification.

---

TypeScript

The package ships full type declarations. Import types alongside values:

import { WebChat, type WebChatHandle } from "@experiaapp/webchat-react-native";

Lower-level building blocks (the theme helpers, media utilities, individual UI pieces, and the video-call primitives) are also exported if you need to compose a custom surface.

---

Troubleshooting

• Native feature does nothing / picker won't open in Expo Go — Expo Go can't load the native modules; use a development build (eas build / expo prebuild).
• Icons render as plain glyphs — install react-native-svg.
• Video-call button missing — set makeVideoCall: true, install the WebRTC peers + plugin, and ensure your channel enables it.
• The same conversation keeps resuming — that's storage: "localStorage" (the default). Use "sessionStorage" to start fresh each launch, or call resetSession().

---

License

MIT Experia App — see LICENSE.