This module allows you to add voice-over-IP (VoIP) calling into your React Native app using Twilio Programmable Voice.
It is built on top of 3 modules:
-
React Native CallKeep: Manage VoIP calls with native UI (CallKit on iOS and ConnectionService on Android)
-
React Native Firebase Messaging: Handle VoIP push notifications on Android
-
React Native VoIP Push Notification: Handle VoIP push notifications on iOS
Supported versions:
- iOS 11+
- Android API 23+
An example app is provided in the example folder. Check below instructions to run it.
Android call to iOS:
iOS call to Android:
Before setting up this module, you need to install the 3 dependencies listed above in your app. Then you have to configure a server that generates an access token used by Twilio.
Install React Native CallKeep and follow their instructions for iOS and Android.
Install React Native Firebase Messaging.
You can skip the iOS installation steps as we use this module only on Android.
Install React Native VoIP Push Notification.
The following modifications must be made on AppDelegate.m
in order to handle Twilio notifications:
// --- Handle incoming pushes (for ios >= 11)
- (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(PKPushType)type withCompletionHandler:(void (^)(void))completion {
// --- Retrieve information from Twilio push payload
NSString *uuid = [[[NSUUID UUID] UUIDString] lowercaseString];
NSString *callerName = [payload.dictionaryPayload[@"twi_from"] stringByReplacingOccurrencesOfString:@"client:" withString:@""];
NSString *handle = [payload.dictionaryPayload[@"twi_to"] stringByReplacingOccurrencesOfString:@"client:" withString:@""];
// --- Process the received push
[RNVoipPushNotificationManager didReceiveIncomingPushWithPayload:payload forType:(NSString *)type];
// --- You should make sure to report to callkit BEFORE execute `completion()`
[RNCallKeep reportNewIncomingCall:uuid
handle:handle
handleType:@"generic"
hasVideo:NO
localizedCallerName:callerName
supportsHolding:YES
supportsDTMF:YES
supportsGrouping:YES
supportsUngrouping:YES
fromPushKit:YES
payload:payload.dictionaryPayload
withCompletionHandler:nil];
completion();
}
Follow the Twilio Voice iOS SDK Quickstart and Android SDK Quickstart.
Steps 1 and 6 must be skipped.
Now come the easy part :)
npm install react-native-twilio-phone
Run this command to complete installation on iOS:
cd ios/ && pod install
You must also create a Swift file like this one in the /ios
folder. If you don't have such a file, your app won't build.
Use RNTwilioPhone
class to easily receive incoming calls or start outgoing calls.
import * as React from 'react';
import { RNTwilioPhone } from 'react-native-twilio-phone';
// ...
// Options passed to CallKeep (https://github.com/react-native-webrtc/react-native-callkeep#setup)
const callKeepOptions = {
ios: {
appName: 'TwilioPhone Example',
supportsVideo: false,
},
android: {
alertTitle: 'Permissions required',
alertDescription: 'This application needs to access your phone accounts',
cancelButton: 'Cancel',
okButton: 'OK',
additionalPermissions: [],
// Required to get audio in background when using Android 11
foregroundService: {
channelId: 'com.example.reactnativetwiliophone',
channelName: 'Foreground service for my app',
notificationTitle: 'My app is running on background',
},
},
};
// Async function that returns Twilio access token
async function fetchAccessToken() {
const response = await fetch(
'https://XXXXXX.ngrok.io/accessToken?identity=alice'
);
const accessToken = await response.text();
return accessToken;
}
// RNTwilioPhone options
const options = {
requestPermissionsOnInit: true, // Default: true - Set to false if you want to request permissions manually
};
export function MyComponent() {
// Initialize once when component did mount
// Execute returned function when component will unmount to avoid memory leaks
React.useEffect(() => {
// This will set up CallKeep and register device for incoming calls
return RNTwilioPhone.initialize(callKeepOptions, fetchAccessToken, options);
// Or use initializeCallKeep if you just want to make outgoing calls
// return RNTwilioPhone.initializeCallKeep(callKeepOptions, fetchAccessToken, options);
}, []);
// Function that starts an outgoing call
async function startCall() {
try {
await RNTwilioPhone.startCall('+00123456789');
} catch (e) {
console.log(e);
}
}
// Call this function to unregister device from incoming calls
// Useful when user signs out for example
async function unregister() {
try {
await RNTwilioPhone.unregister();
} catch (e) {
console.log(e);
}
}
// Display active calls
console.log(RNTwilioPhone.calls);
// ...
}
Thanks to React Native Firebase Messaging and React Native VoIP Push Notification, we can receive calls even when app is killed or running in background.
If you added above code in your AppDelegate.m
, your app is ready to handle notifications in background.
Call RNTwilioPhone.handleBackgroundState()
before your app loading. For example in index.js
:
import { AppRegistry } from 'react-native';
import { RNTwilioPhone } from 'react-native-twilio-phone';
import { name as appName } from './app.json';
import { App } from './src/App';
RNTwilioPhone.handleBackgroundState();
AppRegistry.registerComponent(appName, () => App);
Use twilioPhoneEmitter
to subscribe to module's events:
import { twilioPhoneEmitter } from 'react-native-twilio-phone';
// ...
React.useEffect(() => {
const subscriptions = [
twilioPhoneEmitter.addListener('CallConnected', (data) => {
console.log(data);
}),
twilioPhoneEmitter.addListener('CallDisconnected', (data) => {
console.log(data);
}),
twilioPhoneEmitter.addListener('CallDisconnectedError', (data) => {
console.log(data);
}),
];
return () => {
subscriptions.map((subscription) => {
subscription.remove();
});
};
}, []);
// ...
Following events are available:
enum EventType {
CallInvite = 'CallInvite',
CancelledCallInvite = 'CancelledCallInvite',
CallRinging = 'CallRinging',
CallConnectFailure = 'CallConnectFailure',
CallConnected = 'CallConnected',
CallReconnecting = 'CallReconnecting',
CallReconnected = 'CallReconnected',
CallDisconnected = 'CallDisconnected',
CallDisconnectedError = 'CallDisconnectedError',
RegistrationSuccess = 'RegistrationSuccess',
RegistrationFailure = 'RegistrationFailure',
UnregistrationSuccess = 'UnregistrationSuccess',
UnregistrationFailure = 'UnregistrationFailure',
}
Use TwilioPhone
class to have more control over calls.
type TwilioPhoneType = {
register(accessToken: string, deviceToken: string): void;
handleMessage(payload: MessagePayload): void;
acceptCallInvite(callSid: string): void;
rejectCallInvite(callSid: string): void;
disconnectCall(callSid: string): void;
endCall(callSid: string): void;
toggleMuteCall(callSid: string, mute: boolean): void;
toggleHoldCall(callSid: string, hold: boolean): void;
sendDigits(callSid: string, digits: string): void;
startCall(accessToken: string, params: ConnectParams): void;
unregister(accessToken: string, deviceToken: string): void;
activateAudio(): void; // iOS only
deactivateAudio(): void; // iOS only
checkPermissions(callback: (permissions: Permissions) => void): void;
};
If you don't want to request permissions on initialization, set requestPermissionsOnInit
option to false
:
// ...
export function MyComponent() {
React.useEffect(() => {
return RNTwilioPhone.initialize(callKeepOptions, fetchAccessToken, {
requestPermissionsOnInit: false,
});
}, []);
}
You can request permissions later by calling checkPermissions
method on TwilioPhone
:
TwilioPhone.checkPermissions((permissions) => {
console.log(permissions); // Display the required permissions and their status
});
To start the example app, first set up Twilio server-side web application.
Then run yarn bootstrap
in the root directory to install the required dependencies for each package:
yarn bootstrap
To run the example app on Android:
yarn example android
To run the example app on iOS:
yarn example ios
See the contributing guide to learn how to contribute to the repository and the development workflow.
MIT