React Native

The Voximplant React Native SDK enables real-time audio and video calling, peer-to-peer communication, and multi-party video conferencing in React Native applications for iOS and Android.

Use SDK v2 for all new integrations. It features a modular architecture, separate core and calling modules, and full compatibility with modern React Native environments.

The SDK is split into these packages:

For release history and patch details, see the Changelog.

Ensure your development environment meets the following minimum requirements:

Install both packages together and keep them at the same version, since @voximplant/react-native-calls depends on @voximplant/react-native-core:

npm install @voximplant/react-native-core
npm install @voximplant/react-native-calls

Check the Changelog for the latest release.

Both packages automatically install @voximplant/react-native-shared (containing common types and utilities) as an underlying dependency. You only need to install @voximplant/react-native-shared directly if your application explicitly imports from it.

iOS configuration

The Voximplant React Native SDK is built directly on top of the native Voximplant iOS and Android SDKs. Because the underlying Voximplant iOS SDK is distributed via Swift Package Manager, CocoaPods cannot resolve it automatically. You should explicitly declare the native podspecs in your project's Podfile.

1. Configure the Podfile

Add the podspecs to your target block in ios/Podfile (next to use_native_modules!).

Match your React Native SDK version with the native iOS SDK version below:

In your Podfile, replace <version> with the corresponding version string from the table above:

target 'YourApp' do
  config = use_native_modules!

pod 'VoximplantCore',   :podspec => 'https://github.com/voximplant/ios-sdk-releases/releases/download/<version>/VoximplantCore.podspec'
  pod 'VoximplantCalls',  :podspec => 'https://github.com/voximplant/ios-sdk-releases/releases/download/<version>/VoximplantCalls.podspec'
  pod 'VoximplantWebRTC', :podspec => 'https://github.com/voximplant/ios-sdk-releases/releases/download/<version>/VoximplantWebRTC.podspec'

# use_react_native! and the rest of the target stay as they are
end

Then run pod install in the ios directory:

cd ios && pod install

2. Configure Permissions

If your application uses @voximplant/react-native-calls, add the microphone and camera usage keys to your ios/YourApp/Info.plist file:

<key>NSMicrophoneUsageDescription</key>
<string>This app requires access to the microphone for voice calls.</string>
<key>NSCameraUsageDescription</key>
<string>This app requires access to the camera for video calls.</string>

iOS requires these declarations to display a permission prompt to the user the first time your application attempts to access audio or video hardware. Failing to include these keys will cause your app to crash when initiating or answering a call.

Obtain the Client singleton instance from @voximplant/react-native-core when your application starts. This instance provides the methods to connect and log in:

import { Client } from '@voximplant/react-native-core';

const client = Client.getInstance();

To access Voximplant communication features, your application should establish a connection to the Voximplant Cloud and authenticate a user.

The Client interface provides the API methods for connection and user authentication.

1. Client.connect() — Establishes a connection to the Voximplant Cloud using your account's assigned node.
2. Client.login() — Authenticates user credentials against the platform. Failed Client.connect() and Client.login() calls reject their promises with typed error objects derived from base error classes (ConnectionError and LoginError).

You can use standard try...catch blocks and instanceof checks to handle connection and authentication failures globally:

Connection events and state tracking

While try...catch blocks handle immediate connection failures, monitoring the ongoing lifecycle — such as network drops or state changes — requires listening to Client events and watching the Client.state property.

Key mechanisms:

Subscribe to events with Client.addEventListener() and to state changes with the Watchable.watch() API:

The demo sample lets you try SDK v2 on a phone or simulator. Sign in with a Voximplant user, then make and receive voice and video calls, and join conferences.

Older samples in the same repository are for SDK v1 and are listed in the next section.

React Native SDK v1 will be supported until December 31, 2027, with critical bug fixes only. All new features and platform enhancements are added exclusively to SDK v2.

React Native SDK v1 is distributed as the react-native-voximplant npm package and operates using the Voximplant namespace. For detailed documentation on the legacy API, see the React Native SDK v1 API reference.

NPM

If you use a package manager, install the legacy react-native-voximplant package:

npm install react-native-voximplant --save

SDK v1 relies on native modules, so it does not work in a project created with create-react-native-app, which does not allow custom native modules.

Initialize the SDK

Obtain the client instance with Voximplant.getInstance:

import { Voximplant } from 'react-native-voximplant';

const client = Voximplant.getInstance();

Connect and log in

To establish a connection to the Voximplant Cloud, use the Client.connect method. Once connected, authenticate the user with the Client.login method:

For detailed documentation on the legacy API, see the React Native SDK v1 reference.

The v1 demos are:

• Conference — conference calls, including video and mute.
• Video conference — audio and video calls with push notifications.