React Native Voicebot UI Kit

Requirements

Installation

Add the package

npm install enx-voice-bot-react-native

Or, if the SDK is provided as a local tarball:

npm install file:./enx-voice-bot-react-native-1.0.0.tgz

iOS setup

• Install native pods:

  cd ios && pod install

• Confirm your Podfile platform target is iOS 15.0 or later — the SDK's podspec requires it.
• Add the microphone usage description to Info.plist (see Required Permissions).

Android setup

• No manual linking is required — React Native autolinking registers the SDK's native module.
• Add the required permissions to AndroidManifest.xml (see Required Permissions).
• Rebuild the app:

  npx react-native run-android

Required Permissions MANDATORY

The SDK requests microphone access at runtime before every call, but the underlying platform permission must be declared by the host app.

Android — AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

iOS — Info.plist

<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access to talk to the voice bot.</string>

Runtime permission flow

When EnxVoiceClient.connect() is called, the SDK automatically checks the microphone permission and requests it if it has not been granted yet. If the user denies the permission, connect() fails and the listener's onError() callback receives an error message — no call is placed.

Configuration

Use EnxSdkConfig to choose which EnableX environment the SDK talks to.

For a custom endpoint (for example, a private or regional deployment), build a config from an environment object:

import { EnxSdkConfig } from 'enx-voice-bot-react-native';

const config = EnxSdkConfig.fromEnvironment(
  { name: 'Staging', callApiBaseUrl: 'https://voiceagent-staging.example.com' },
  { enableLogging: true },
);

You can also override the call API base URL for a single call without changing the SDK config, by passing callApiBaseUrl to connect() — see Connect and disconnect.

Integration Steps

1. Install the package and, on iOS, run pod install (see Installation above).
2. Add the Android manifest permissions and the iOS Info.plist microphone usage description (see Required Permissions above).
3. Implement EnxVoiceListener to receive call, mute, error, and speaking-state callbacks — see the Usage Example.
4. Create an EnxVoiceClient, call .init(virtualNumber), .setEnxVoiceListener(...), and .setSdkConfig(EnxSdkConfig.qa or .production).
5. Call connect() to start a call and disconnect() to end it; use muteAudio() and sendDtmf() as needed during the call.
6. Switch to EnxSdkConfig.production (or fromEnvironment with enableLogging: false) before release builds to disable verbose SDK logging.
7. Test on real Android and iOS devices — see Developer Troubleshooting if a call fails to connect.

Module Exports

Import everything from the package root:

import {
  EnxVoiceClient,
  EnxVoiceListener,
  EnxVoiceState,
  EnxSdkConfig,
  EnxVoiceEnvironment,
} from 'enx-voice-bot-react-native';

EnxVoiceClient class

Controls the lifecycle of a single outbound voice bot call: requesting permissions, calling the REST API, opening the Pipecat WebSocket, and streaming audio.

Constructor

new EnxVoiceClient()

Creates a new client with its own audio player and recorder. Each instance manages at most one call at a time.

Configuration methods

setSdkConfig(config: EnxSdkConfig): EnxVoiceClient

Sets the environment (QA/Production/custom) and logging behavior used for subsequent connect() calls. Returns this for chaining.

init(virtualNumber: string): EnxVoiceClient

Sets the virtual number (E.164 format) that will be dialed when connect() is called. Returns this for chaining.

setEnxVoiceListener(listener: EnxVoiceListener): EnxVoiceClient

Registers the listener that receives call, mute, error, and speaking-state callbacks. Returns this for chaining.

setOnDtmfKeypadChanged(callback?: (showKeypad: boolean) => void): EnxVoiceClient

Registers a callback invoked when the active call session reports whether DTMF keypad input is available. Returns this for chaining.

Call control methods

connect(args?: { callApiBaseUrl?: string }): Promise<void>

Starts a call: verifies/requests the microphone permission, initializes native audio, calls POST /v2token, and opens the WebSocket media session. If callApiBaseUrl is omitted, the URL from the configured EnxSdkConfig environment is used. Emits onStatus(connecting) then either onStatus(connected) or onStatus(failed) via the listener.

disconnect(): Promise<void>

Ends the active call: deletes the REST call session, closes the WebSocket, stops audio capture/playback, and resets internal state. Emits onStatus(disconnected) and onCallDisconnect().

muteAudio(isMute: boolean): Promise<boolean>

Mutes or unmutes the microphone. Returns true on success, false if an error occurred. Emits onMuteStateChanged() on success.

isMuted(): boolean

Returns the current microphone mute state.

sendDtmf(digits: string): Promise<boolean>

Sends DTMF digits (0–9, *, #) to the active call session via POST /v2token/{voiceId}/dtmf. Returns false if there is no active session, the input is empty, or it contains invalid characters.

Read-only properties

EnxVoiceListener interface

Implement this interface and pass it to setEnxVoiceListener() to receive call events.

EnxVoiceState enum

EnxSdkConfig class

Holds the REST environment and logging preference used by EnxVoiceClient.

Static members

Static method

EnxSdkConfig.fromEnvironment(
  environment: EnxVoiceEnvironment,
  opts?: { enableLogging?: boolean }
): EnxSdkConfig

Builds a config from a custom or predefined environment. If opts.enableLogging is omitted, logging defaults to disabled for the production environment and enabled otherwise.

Instance members

EnxVoiceEnvironment type

Predefined constants: EnxVoiceEnvironment.qa and EnxVoiceEnvironment.production. Supply your own object with the same shape to target a custom deployment.

REST API Reference

EnxVoiceClient calls the following EnableX Voice Agent REST endpoints internally. They are documented here for troubleshooting and for advanced integrations that need to call them directly.

Start a call

POST {callApiBaseUrl}/v2token
Content-Type: application/json

Request body:

{
  "phone": "<virtual number, E.164>"
}

On success, returns HTTP 200 with a JSON body containing voice_id (or voiceId), a WebSocket URL (wss_host / wss_url / wssUrl / pipecat_url / url), and an optional dtmf flag.

Used by EnxVoiceClient.connect().

End a call

DELETE {callApiBaseUrl}/v2token/{voiceId}

Returns HTTP 200 on success. Used by EnxVoiceClient.disconnect() (only if the call was successfully started).

Send DTMF digits

POST {callApiBaseUrl}/v2token/{voiceId}/dtmf
Content-Type: application/json

Request body:

{
  "digits": "<0-9, *, #>"
}

Returns HTTP 200 on success. Used by EnxVoiceClient.sendDtmf(digits).

Media WebSocket

After POST /v2token succeeds, the SDK opens a WebSocket connection to the returned URL and exchanges binary, protobuf-framed Pipecat messages: outgoing 16 kHz mono PCM microphone audio frames, and incoming bot audio frames plus JSON control events such as bot-started-speaking, bot-stopped-speaking, user-started-speaking, and user-stopped-speaking.

Low-Level Helpers advanced

These are exported for custom integrations and testing; most applications should use EnxVoiceClient instead of calling them directly.

Usage Example

Implement the listener

Your app implements EnxVoiceListener to receive call state, speaking state, mute state, and error events.

import {
  EnxVoiceClient,
  type EnxVoiceListener,
  EnxVoiceState,
  EnxSdkConfig,
} from 'enx-voice-bot-react-native';

class MyVoiceListener implements EnxVoiceListener {
  onCallConnected() { /* update UI: call is live */ }
  onCallDisconnect() { /* update UI: call ended */ }
  onError(message: string) { /* show an error toast */ }
  onMuteStateChanged(isMuted: boolean) { /* toggle mute icon */ }
  onStatus(state: EnxVoiceState) { /* connecting / connected / disconnected / failed */ }
  onUserSpeaking(isUserSpeaking: boolean) { /* animate mic indicator */ }
  onBotSpeaking(isBotSpeaking: boolean) { /* animate bot indicator */ }
}

Create and configure the client

const client = new EnxVoiceClient()
  .init('911100123457')            // virtual number to dial
  .setEnxVoiceListener(new MyVoiceListener())
  .setSdkConfig(EnxSdkConfig.qa);   // or EnxSdkConfig.production

Connect and disconnect

// Start a call
await client.connect();

// Optionally override the REST base URL for this call only
await client.connect({ callApiBaseUrl: 'https://voiceagent.enablex.io' });

// End the call
await client.disconnect();

Mute and unmute the microphone

await client.muteAudio(true);   // mute
await client.muteAudio(false);  // unmute
client.isMuted();               // current mute state

Send DTMF digits

If the bot session supports a DTMF keypad, the listener's onDtmfKeypadChanged callback (set via setOnDtmfKeypadChanged) is notified so your app can show a keypad. Digits are sent with:

const sent = await client.sendDtmf('123#');

sendDtmf() accepts digits 0–9, * and #, and returns false if there is no active call session or the input is invalid.

React to speaking state

While a call is active, onUserSpeaking(true/false) and onBotSpeaking(true/false) fire as the bot's voice-activity detector toggles. The SDK automatically pauses microphone upload while the bot is speaking and resumes it shortly after the bot stops, to avoid echo/overlap.

Feature Support (v1.0.0)

Known Issues & Limitations

• Outbound calls only — the SDK initiates calls to a virtual number; there is no inbound call handling.
• One active call per EnxVoiceClient instance — create a new instance (or fully disconnect) before starting another call.
• No automated test suite is published with this release (npm test is a placeholder).
• DTMF sending requires the bot session to report keypad support; otherwise sendDtmf() returns false.
• Verbose debug logging is enabled by default under the QA configuration; use EnxSdkConfig.production or set enableLogging: false for release builds.

Developer Troubleshooting

Upgrade Notes

• This is the first published version; there are no breaking changes to migrate from.
• When upgrading in the future, re-run pod install in the iOS project after bumping the package version, since native iOS sources ship inside the pod.
• Review EnxSdkConfig usage before release builds — use EnxSdkConfig.production (or fromEnvironment with enableLogging: false) to disable verbose SDK logging.