dialogs_chatbot_reactnative

Version: 1.0.0 — first npm release

Add EnableX Dialogs chat to your React Native app with ready-made screens and components (EnxChatWidget, EnxChatScreen).

Table of contents

1. Requirements
2. Installation
3. Permissions
4. Credentials
5. How to use
6. Widget options
7. What your users get
8. Example app

New to the SDK? Start with USER_GUIDE.md for a step-by-step walkthrough.

Requirements

| Item | Version | |------|---------| | React | ≥ 18 | | React Native | ≥ 0.76 (the sample app in this repo uses 0.84) | | Node.js | Match what your React Native version recommends (sample app: ≥ 22) |

Set up your machine using the official React Native environment guide.

Installation

npm packages

Install the SDK and its companion libraries (keep major versions aligned with your app when possible):

npm install [email protected] \
  react-native-webview \
  react-native-image-picker \
  @react-native-documents/picker \
  @react-native-community/datetimepicker \
  lucide-react-native \
  react-native-markdown-display \
  react-native-svg \
  react-native-video

iOS — CocoaPods

cd ios && pod install && cd ..

Rebuild the app after adding native modules.

Permissions

Your bot and the chat UI may use network, camera, microphone, location, photos, and files. Declare only what you need; the tables below cover typical cases.

Android (AndroidManifest.xml)

Declare permissions outside <application>:

| Permission | When you need it | |------------|------------------| | INTERNET | Always — chat and media load over the network. | | CAMERA | Camera in video chat or attachments. | | RECORD_AUDIO | Microphone in calls or video chat. | | MODIFY_AUDIO_SETTINGS | Often used together with voice/video. | | ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION | If the chat uses location, or you enable early location prompts (see proactiveLocationPermission under Widget options). |

Optional hardware flags so the app can still install on devices without a camera or mic:

<uses-feature android:name="android.hardware.camera" android:required="false" />
<uses-feature android:name="android.hardware.microphone" android:required="false" />

Example manifest block (same pattern as the sample app in this repository):

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-feature android:name="android.hardware.camera" android:required="false" />
    <uses-feature android:name="android.hardware.microphone" android:required="false" />

    <application ...>
        ...
    </application>
</manifest>

When Android asks the user

• Camera and microphone may be requested when a video session starts from the chat (for example after the bot opens a video room).
• Location is requested on first use by the chat, or up front on Android if you set proactiveLocationPermission={true} on the widget (default is false).

If the user denies a permission, only the features that need it are affected; plain text chat may still work.

Photos and files on older Android versions may need extra read permissions. See the docs for react-native-image-picker and @react-native-documents/picker.

Keyboard: on your main activity, android:windowSoftInputMode="adjustResize" helps keep the message field visible above the keyboard (the sample app uses this).

iOS (Info.plist)

Add a usage description for each capability you use. Missing keys can cause crashes or blocked access when the system shows a privacy prompt.

| Key | Typical purpose | |-----|------------------| | NSCameraUsageDescription | Camera in video chat or capture. | | NSMicrophoneUsageDescription | Microphone in audio or video chat. | | NSLocationWhenInUseUsageDescription | Location features inside the chat. | | NSPhotoLibraryUsageDescription | Choosing photos to send in chat. | | NSPhotoLibraryAddUsageDescription | Saving images to the library, if your flow needs it. |

Example (adjust the user-visible strings for your app and App Store review):

<key>NSCameraUsageDescription</key>
<string>Camera is used for video calls with the support agent.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone is used for audio and video calls with the support agent.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location may be used when the chat requests it (for example maps or regional features).</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access lets you attach images in chat.</string>

App Transport Security (ATS): use HTTPS for your Dialogs host in production. Avoid broad “allow all HTTP” settings unless your security team requires them.

Credentials

From the EnableX / Dialogs console:

| Field | Description | |-------|-------------| | botId | Your bot identifier. | | host | Service base URL, e.g. https://dialogs.enablex.io. |

Optional EnxBotConfig fields rootPath and callingEnabled — use only if your EnableX deployment guide says so.

How to use

Option A — Simplest (recommended to start)

Pass config. The widget creates its own EnxChatController and cleans up when it unmounts.

import React from 'react';
import { View } from 'react-native';
import { EnxChatWidget, mobileClassicTheme } from 'dialogs_chatbot_reactnative';

export function SupportChat() {
  return (
    <View style={{ flex: 1 }}>
      <EnxChatWidget
        config={{
          botId: 'YOUR_BOT_ID',
          host: 'https://dialogs.enablex.io',
        }}
        theme={mobileClassicTheme}
      />
    </View>
  );
}

Option B — You keep the controller

Use EnxChatController when you want one instance for longer than a single screen or you wire extra app logic around it. Call dispose() when you are done (for example in a useEffect cleanup).

import React, { useEffect, useRef } from 'react';
import { View } from 'react-native';
import { EnxChatController, EnxChatWidget, mobileClassicTheme } from 'dialogs_chatbot_reactnative';

export function SupportChat() {
  const controllerRef = useRef(
    new EnxChatController({
      botId: 'YOUR_BOT_ID',
      host: 'https://dialogs.enablex.io',
    }),
  );

  useEffect(() => {
    const c = controllerRef.current;
    return () => {
      void c.dispose();
    };
  }, []);

  return (
    <View style={{ flex: 1 }}>
      <EnxChatWidget controller={controllerRef.current} theme={mobileClassicTheme} />
    </View>
  );
}

Option C — Screen with title and back button

import { EnxChatScreen, mobileClassicTheme } from 'dialogs_chatbot_reactnative';

<EnxChatScreen
  title="Support"
  onBack={() => { /* e.g. navigation.goBack() */ }}
  config={{ botId: 'YOUR_BOT_ID', host: 'https://dialogs.enablex.io' }}
  theme={mobileClassicTheme}
  showCallingOptions
/>

Audio / video calling from the chat bar

Set showCallingOptions to show call actions. Implement onAudioCall and onVideoCall to open your own calling solution (the sample app uses simple alerts as placeholders).

Widget options

| Prop | Description | |------|-------------| | config | Bot id and host — required if you do not pass controller. | | controller | Your EnxChatController. If omitted, the widget builds one from config. | | theme | mobileClassicTheme, defaultTheme, or your own partial theme object. | | showCallingOptions | Show audio/video actions; use with onAudioCall / onVideoCall. | | onBotInfo | Called with bot metadata (for example display name) when available. | | onMessageReceived / onMessageSent | Fired when messages arrive or are sent. | | onError | Connection or chat errors (message, type). | | onVideoCallRequest | Bot started a video session; you may handle the URL yourself or rely on the default full-screen presentation. | | onVideoCallEnded | Bot ended the video session. | | proactiveLocationPermission | Android only. Default false. If true, the app can ask for location when the chat opens instead of waiting until the chat needs it. |

What your users get

• Conversation list, message bubbles, typing indicator, and text input
• Rich content supported by your bot (for example markdown, images, files, video playback where configured)
• Optional audio/video actions you connect to your own calling product
• Light theming via theme

Before you ship your app

• Confirm botId and host point at your production EnableX / Dialogs environment.
• Match permissions and iOS usage descriptions to what your bot actually uses (see Permissions).
• Test on real Android and iOS devices: text chat, attachments, location, and video if you enable those flows.
• Prefer HTTPS for your dialogs host; avoid overly broad ATS or cleartext exceptions in production unless your security team requires them.

If you develop inside this monorepo, run npm run typecheck and npm test from the repository root after npm run bootstrap (commands are listed in the root README.md of this repo).

Example app

This repository includes a sample under packages/example (App.tsx). For install and run commands, see packages/example/README.md.