React Native Chatbot UI Kit

Requirements

Installation

Install the SDK and its companion libraries

npm install dialogs_chatbotav_reactnative \
  [email protected] \
  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

Calling dependencies

Audio calls, video calls, and click-to-call are powered by three native modules working together. All three are mandatory for calling — the feature does not work with only one or two of them, even though react-native-webview is the only one of the three you also install yourself:

enx-uikit-react-native additionally declares these as peer dependencies. Install them in your app if you use native (click-to-call / UIKit) video sessions:

npm install react-native-gesture-handler react-native-reanimated \
  @react-navigation/native @react-navigation/stack

Minimum versions: react-native-gesture-handler ≥ 2.24.0, react-native-reanimated ≥ 4.2.0, @react-navigation/native and @react-navigation/stack ≥ 7.0.0.

iOS — CocoaPods

cd ios && pod install && cd ..

Rebuild the app after adding native modules (Xcode: Product › Clean Build Folder, then run).

Android — required Gradle configuration

Add the following block to your app-level android/app/build.gradle, inside the dependencies section (or immediately above it). It excludes a duplicate legacy library pulled in by enx-rtc-react-native that otherwise fails the build with a “Duplicate class” error:

configurations.all {
    exclude group: 'android.arch.lifecycle', module: 'extensions'
}

See Developer Troubleshooting if you hit build errors even after adding this — it covers two additional known issues and their fixes in detail.

Required Permissions MANDATORY

The chat and calling features rely on the OS permissions below. Declare only what your bot actually uses.

Android — AndroidManifest.xml

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" />

Full example manifest block:

<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>

iOS — Info.plist

<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.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access lets you attach images in chat.</string>

Credentials

From the EnableX / Dialogs console:

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

Integration Steps

1. Install the SDK and its companion libraries, pinning react-native-webview to exactly 13.16.1 (see Installation above).
2. Add the required Android manifest permissions and iOS Info.plist usage-description keys (see Required Permissions above).
3. iOS: run pod install. Android: add the Gradle exclusion for android.arch.lifecycle:extensions.
4. Render EnxChatWidget or EnxChatScreen with your botId/host — see the Usage Example.
5. Set showCallingOptions if you want audio/video call buttons in the input bar; implement onAudioCall/onVideoCall to fully own the call UI, or let the widget handle bot-initiated calls automatically.
6. Do a full clean native rebuild any time the SDK or its native dependencies change version (Android: ./gradlew clean; iOS: pod install + Clean Build Folder).
7. Test text chat, attachments, and calling on real iOS and Android devices — see Developer Troubleshooting if a native build fails.

Data Types & Enums

Import everything from the package root: import { EnxChatWidget, EnxChatController, /* ... */ } from 'dialogs_chatbotav_reactnative';

EnxBotConfig

Configuration passed to EnxChatController or the config prop of EnxChatWidget / EnxChatScreen.

EnxMessageSender

Enum identifying who sent a message.

EnxMessageType

EnxSuggestionType

EnxConnectionStatus

Exposed as EnxChatController.status; drives the widget's connection banner.

EnxChoice

EnxAction

EnxMedia

EnxLinkCard

Rich link / company preview card rendered instead of a plain URL + file row.

EnxMessageDisplayStyle

Type: 'default' | 'systemCentered'. When systemCentered, the message renders as a full-width centered notice chip instead of a side bubble (handover, agent assigned, dropped, etc.).

EnxMessage

The core chat message model. Every message the controller emits or accepts is shaped like this.

EnxChatTheme & default themes

Two ready-made theme constants are exported:

• defaultTheme — WhatsApp-style green theme.
• mobileClassicTheme — matches the EnableX mobile web chat look.

Components

EnxChatWidget

The primary embeddable chat UI. Renders the message list, input bar, connection banner, and (on Android) the hidden WebView bridge or video overlay.

<EnxChatWidget config={{ botId, host }} theme={mobileClassicTheme} />

EnxChatScreen

A full-screen wrapper around EnxChatWidget with a header (title + optional back button).

ChatList

The scrolling message list used internally by EnxChatWidget. Exported for advanced/custom layouts.

Accepts a ref of type ChatListHandle, exposing scrollToBottom(animated: boolean): void.

MessageCell

Renders a single message bubble (text, image, video, file, suggestions, actions, or calendar prompt). Exported for custom list implementations.

InputBar

The bottom text field, attachment picker, and audio/video call buttons.

TypingBubble

Three-dot animated typing indicator.

ChatMarkdown

Renders bot message text with markdown formatting (links, emphasis, lists).

EnxChatController

A framework-agnostic connection and message controller. EnxChatWidget creates one internally if you do not supply your own; you can also own an instance yourself and drive fully custom UI off it.

Constructor

new EnxChatController(config: EnxBotConfig)

Properties (read-only getters)

Event callbacks (assign directly)

Methods

Hooks

useControllerVersion

function useControllerVersion(controller: EnxChatController): number

Subscribes a component to an EnxChatController and forces a re-render whenever its state changes. Returns an incrementing version number (the value itself is not meaningful — only the fact that it changed).

const version = useControllerVersion(controller);
// component re-renders on every controller.messages / status / isTyping change

Media & Permission Helpers

cachedImageSource

function cachedImageSource(uri: string): ImageURISource

Returns an Image source. Remote HTTP(S) URLs get { cache: 'default' } so the platform HTTP cache (honoring Cache-Control from the server) is used; local/data URIs pass through unchanged.

cachedVideoSource

function cachedVideoSource(uri: string): { uri: string; isNetwork?: boolean; shouldCache?: boolean }

Returns a react-native-video source. Remote HTTP(S) URLs get isNetwork: true and shouldCache: true for disk-cached repeat playback; local/content URIs pass through unchanged.

requestCameraAndMicrophoneForMedia

function requestCameraAndMicrophoneForMedia(): Promise<void>

Android only (no-op on iOS, where the system prompt is triggered automatically). Requests CAMERA and RECORD_AUDIO together. Called automatically by EnxChatWidget immediately before a video call starts; denial is silent — the video UI may still open and show its own message.

requestLocationForWebView

function requestLocationForWebView(): Promise<void>

Android only. Requests ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION together. Call this yourself only if you opted into proactiveLocationPermission on the widget; otherwise the WebView requests location natively when the chat page calls navigator.geolocation.

Message Parsing Utilities

Lower-level helpers used internally to interpret the raw bridge payload. Most integrations do not need to call these directly — EnxChatController already applies them.

parseBridgeMessage

function parseBridgeMessage(rawData: unknown): EnxMessage[]

Converts a raw bridge payload into zero or more EnxMessage objects.

extractVideoCallUrl

function extractVideoCallUrl(rawData: unknown, botDisplayName?: string): string | undefined

Extracts a video-room URL from a raw bridge payload, if present.

extractVideoCallRoomToken

function extractVideoCallRoomToken(rawData: unknown): string | undefined

Extracts a native EnableX UIKit room token from a raw bridge payload, if present.

isAudioVideoStopPayload

function isAudioVideoStopPayload(rawData: unknown): boolean

True if the payload represents the bot ending an audio/video session (audio_video_action: stop).

EnxWebViewBridge

The platform bridge that connects the chat page to native code — a hidden WebView on Android, or the native EnxChatBridge module on iOS. Accessed via controller.bridge. Most apps never need to call this directly; it is documented here for advanced integrations that fully replace the default widget UI.

formatMultiSuggestionWireText

function formatMultiSuggestionWireText(values: string[]): string

Formats a list of selected multi-suggestion titles into the JSON-array wire text the bot echoes back. Used internally to de-duplicate the echo against the locally-rendered user message.

Usage Example

Simplest — pass config directly

The widget creates and owns its own EnxChatController, and disposes it automatically when it unmounts.

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

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

Own the controller yourself

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

import React, { useEffect, useRef } from 'react';
import { View } from 'react-native';
import { EnxChatController, EnxChatWidget, mobileClassicTheme } from 'dialogs_chatbotav_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>
  );
}

Full screen with a title bar and back button

import { EnxChatScreen, mobileClassicTheme } from 'dialogs_chatbotav_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 in the input bar. Implement onAudioCall and onVideoCall to open your own calling flow if you want to override the default behavior. When the bot itself starts a video session, the widget requests camera/microphone permission and opens the call automatically — as a full-screen native view on iOS, or a WebView / native UIKit overlay on Android — unless you handle onVideoCallRequest yourself.

This entire flow — audio calls, video calls, and click-to-call handoff to a native room — runs on top of enx-rtc-react-native (the WebRTC media engine) and enx-uikit-react-native (the native call screen), with react-native-webview carrying signaling and rendering the Android in-app overlay. All three must be present and correctly built for calling to work; see Calling dependencies above, and Developer Troubleshooting if a build fails.

Widget Configuration Reference

The most commonly used EnxChatWidget props — see Components above for the complete, exhaustive reference.

Feature Support (v1.0.0)

Known Issues in Upstream Dependencies

These are pre-existing issues in third-party packages this SDK depends on. They are documented here so you are not blocked by them — fixes for each are covered in Developer Troubleshooting below.

• Android build fails with a CMake “add_subdirectory” error. On React Native New Architecture builds, enx-uikit-react-native's Android build script incorrectly registers itself for native TurboModule/Fabric codegen even though it ships no codegen spec files. See fix.
• Android build fails with “Duplicate class” errors. enx-rtc-react-native pulls in the long-abandoned android.arch.lifecycle:extensions library, whose classes duplicate ones already shipped by AndroidX. See fix.
• TypeScript error referencing react-native-webview's WebView type. Versions 13.16.2+ ship a typing regression that breaks any code referencing the bare WebView type. This SDK pins to 13.16.1. See fix.

Breaking changes: none — this is the first public release.

Developer Troubleshooting

Android build fails: CMake “add_subdirectory” error mentioning enx-uikit-react-native

Cause: enx-uikit-react-native's Android build script registers the module for New Architecture codegen even though it ships no codegen spec files, which breaks the native build:

CMake Error ... add_subdirectory given source
".../node_modules/enx-uikit-react-native/android/build/generated/source/codegen/jni/"
which is not an existing directory.

Fix — install patch-package and remove the offending Gradle block:

1. Install patch-package as a dev dependency:

   npm install -D patch-package

2. Open node_modules/enx-uikit-react-native/android/build.gradle and delete this block entirely (do not just comment it out — see the note below):

   if (isNewArchitectureEnabled()) {
     react {
       jsRootDir = file("../src/")
       libraryName = "EnxUikitReactNative"
       codegenJavaPackageName = "com.enxuikitreactnative"
     }
   }

3. Generate a patch and wire it to auto-apply on every install:

   npx patch-package enx-uikit-react-native
   # add to package.json scripts:
   "postinstall": "patch-package"

4. Commit the generated patches/ folder to version control.
5. Clean the stale autolinking cache and rebuild:

   rm -rf android/build android/app/build android/app/.cxx
   cd android && ./gradlew :app:assembleDebug

Android build fails: “Duplicate class” errors mentioning support-compat

Cause: enx-rtc-react-native depends on the long-abandoned android.arch.lifecycle:extensions library, whose classes duplicate ones already provided by AndroidX.

Fix: add this exclusion to your app-level android/app/build.gradle (see Installation):

configurations.all {
    exclude group: 'android.arch.lifecycle', module: 'extensions'
}

TypeScript error: “No overload matches this call” on <WebView />

Cause: react-native-webview 13.16.2 and later ship a typing regression — the WebView class's generic default became undefined instead of {}, which makes WebViewProps & undefined resolve to never for any code referencing the bare WebView type (for example useRef<WebView>()).

Fix: pin react-native-webview to exactly 13.16.1 in your app's package.json:

"react-native-webview": "13.16.1"

Then reinstall so the exact version resolves in your lockfile:

npm install [email protected] --save-exact

“Install via USB” / INSTALL_FAILED_USER_RESTRICTED on Android

Cause: some OEM Android skins (Xiaomi/MIUI, Samsung, Vivo, Oppo, etc.) block sideloaded installs unless an extra developer option is enabled.

Fix: on the device, enable Settings → Developer options → Install via USB, then retry.

Before You Ship

• Confirm botId and host point at your production EnableX / Dialogs environment.
• Match permissions and iOS usage descriptions to what your bot actually uses (see Required 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 required.
• Do a full clean native rebuild (Android: ./gradlew clean; iOS: pod install + Clean Build Folder) any time the SDK or its native dependencies change version.