react-native-twilio-programmable-voice

This is a React-Native wrapper for Twilio Programmable Voice SDK which lets you make and receive calls from your React-Native App. This module is not affiliated with nor officially maintained by Twilio, and it is maintained by open source contributors.

Twilio Programmable Voice SDK

• Android 4.5.0 (bundled within the module)
• iOS 5.1.0 (specified by the app's own podfile)

Breaking changes in v4.0.0

The module implements react-native autolinking as many other native libraries > react-native 0.60.0, therefore it doesn't need to be linked manually.

Android: update Firebase Messaging to 17.6.+. Remove the following block from your application's AndroidManifest.xml if you are migrating from v3.

1    <!-- [START instanceId_listener] -->
2    <service
3        android:name="com.hoxfon.react.TwilioVoice.fcm.VoiceFirebaseInstanceIDService"
4        android:exported="false">
5        <intent-filter>
6            <action android:name="com.google.android.gms.iid.InstanceID" />
7        </intent-filter>
8    </service>
9    <!-- [END instanceId_listener] -->

Android X is supported.

Data passed to the event deviceDidReceiveIncoming does not contain the key call_state, because state of Call Invites was removed in Twilio Android and iOS SDK v3.0.0

• iOS: params changes for connectionDidConnect and connectionDidDisconnect

  to => call_to from => call_from error => err

New features

Twilio Programmable Voice SDK v3.0.0 handles call invites directly and makes it easy to distinguish a call invites from an active call, which previously was confusing. To ensure that an active call is displayed when the app comes to foreground you should use the promise getActiveCall(). To ensure that a call invite is displayed when the app comes to foreground use the promise getCallInvite(). Please note that call invites don't have a call_state field.

You should use hold() to put a call on hold.

You can be notified when a call is ringing by listening for callStateRinging events.

iOS application can now receive the following events, that in v3 where only dispatched to Android:

• deviceDidReceiveIncoming
• callInviteCancelled
• callStateRinging
• connectionIsReconnecting
• connectionDidReconnect

Breaking changes in v3.0.0

• initWitToken returns an object with a property initialized instead of initilized
• iOS event connectionDidConnect returns the same properties as Android move property to => call_to move property from => call_from

Installation

Before starting, we recommend you get familiar with Twilio Programmable Voice SDK. It's easier to integrate this module into your react-native app if you follow the Quick start tutorial from Twilio, because it makes very clear which setup steps are required.

1npm install react-native-twilio-programmable-voice --save

• React Native 0.60+

CLI autolink feature links the module while building the app.

• React Native <= 0.59

1react-native link react-native-twilio-programmable-voice

iOS Installation

If you can't or don't want to use autolink, you can also manually link the library using the instructions below (click on the arrow to show them):

Edit your Podfile to include TwilioVoice framework

1source 'https://github.com/cocoapods/specs'
2
3# min version for TwilioVoice to work
4platform :ios, '10.0'
5
6target <YOUR_TARGET> do
7    ...
8    pod 'TwilioVoice', '~> 5.2.0'
9    ...
10end

1cd ios/ && pod install

CallKit

The iOS library works through CallKit and handling calls is much simpler than the Android implementation as CallKit handles the inbound calls answering, ignoring, or rejecting. Outbound calls must be controlled by custom React-Native screens and controls.

To pass caller's name to CallKit via Voip push notification add custom parameter 'CallerName' to Twilio Dial verb.

1    <Dial>
2    <Client>
3        <Identity>Client</Identity>
4        <Parameter name="CallerName">NAME TO DISPLAY</Parameter>
5    </Client>
6    </Dial>

VoIP Service Certificate

Twilio Programmable Voice for iOS utilizes Apple's VoIP Services and VoIP "Push Notifications" instead of FCM. You will need a VoIP Service Certificate from Apple to receive calls. Follow the official Twilio instructions to complete this step.

Android Installation

Setup FCM

You must download the file google-services.json from the Firebase console. It contains keys and settings for all your applications under Firebase. This library obtains the resource senderID for registering for remote GCM from that file.

android/build.gradle

1buildscript {
2    dependencies {
3        // override the google-service version if needed
4        // https://developers.google.com/android/guides/google-services-plugin
5        classpath 'com.google.gms:google-services:4.3.3'
6    }
7}
8
9// this plugin looks for google-services.json in your project
10apply plugin: 'com.google.gms.google-services'

AndroidManifest.xml

1    <uses-permission android:name="android.permission.VIBRATE" />
2
3    <application ....>
4        <!-- Twilio Voice -->
5        <!-- [START fcm_listener] -->
6        <service
7            android:name="com.hoxfon.react.RNTwilioVoice.fcm.VoiceFirebaseMessagingService">
8            <intent-filter>
9                <action android:name="com.google.firebase.MESSAGING_EVENT" />
10            </intent-filter>
11        </service>
12        <!-- [END fcm_listener] -->

If you can't or don't want to use autolink, you can also manually link the library using the instructions below (click on the arrow to show them):

1include ':react-native-twilio-programmable-voice'
2project(':react-native-twilio-programmable-voice').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-twilio-programmable-voice/android')

1dependencies {
2   implementation project(':react-native-twilio-programmable-voice')
3}

1import com.hoxfon.react.RNTwilioVoice.TwilioVoicePackage;  // <--- Import Package

1@Override
2protected List<ReactPackage> getPackages() {
3    return Arrays.asList(
4            new MainReactPackage(),
5            new TwilioVoicePackage()         // <---- Add the package
6            // new TwilioVoicePackage(false) // <---- pass false if you don't want to ask for microphone permissions
7    );
8}

Usage

1import TwilioVoice from 'react-native-twilio-programmable-voice'
2
3// ...
4
5// initialize the Programmable Voice SDK passing an access token obtained from the server.
6// Listen to deviceReady and deviceNotReady events to see whether the initialization succeeded.
7async function initTelephony() {
8    try {
9        const accessToken = await getAccessTokenFromServer()
10        const success = await TwilioVoice.initWithToken(accessToken)
11    } catch (err) {
12        console.err(err)
13    }
14}
15
16function initTelephonyWithToken(token) {
17    TwilioVoice.initWithAccessToken(token)
18
19    // iOS only, configure CallKit
20    try {
21        TwilioVoice.configureCallKit({
22            appName:       'TwilioVoiceExample',                  // Required param
23            imageName:     'my_image_name_in_bundle',             // OPTIONAL
24            ringtoneSound: 'my_ringtone_sound_filename_in_bundle' // OPTIONAL
25        })
26    } catch (err) {
27        console.err(err)
28    }
29}

Events

1// add listeners (flowtype notation)
2TwilioVoice.addEventListener('deviceReady', function() {
3    // no data
4})
5TwilioVoice.addEventListener('deviceNotReady', function(data) {
6    // {
7    //     err: string
8    // }
9})
10TwilioVoice.addEventListener('connectionDidConnect', function(data) {
11    // {
12    //     call_sid: string,  // Twilio call sid
13    //     call_state: 'CONNECTED' | 'ACCEPTED' | 'CONNECTING' | 'RINGING' | 'DISCONNECTED' | 'CANCELLED',
14    //     call_from: string, // "+441234567890"
15    //     call_to: string,   // "client:bob"
16    // }
17})
18TwilioVoice.addEventListener('connectionIsReconnecting', function(data) {
19    // {
20    //     call_sid: string,  // Twilio call sid
21    //     call_from: string, // "+441234567890"
22    //     call_to: string,   // "client:bob"
23    // }
24})
25TwilioVoice.addEventListener('connectionDidReconnect', function(data) {
26    // {
27    //     call_sid: string,  // Twilio call sid
28    //     call_from: string, // "+441234567890"
29    //     call_to: string,   // "client:bob"
30    // }
31})
32TwilioVoice.addEventListener('connectionDidDisconnect', function(data: mixed) {
33    //   | null
34    //   | {
35    //       err: string
36    //     }
37    //   | {
38    //         call_sid: string,  // Twilio call sid
39    //         call_state: 'CONNECTED' | 'ACCEPTED' | 'CONNECTING' | 'RINGING' | 'DISCONNECTED' | 'CANCELLED',
40    //         call_from: string, // "+441234567890"
41    //         call_to: string,   // "client:bob"
42    //         err?: string,
43    //     }
44})
45TwilioVoice.addEventListener('callStateRinging', function(data: mixed) {
46    //   {
47    //       call_sid: string,  // Twilio call sid
48    //       call_state: 'CONNECTED' | 'ACCEPTED' | 'CONNECTING' | 'RINGING' | 'DISCONNECTED' | 'CANCELLED',
49    //       call_from: string, // "+441234567890"
50    //       call_to: string,   // "client:bob"
51    //   }
52})
53TwilioVoice.addEventListener('callInviteCancelled', function(data: mixed) {
54    //   {
55    //       call_sid: string,  // Twilio call sid
56    //       call_from: string, // "+441234567890"
57    //       call_to: string,   // "client:bob"
58    //   }
59})
60
61// iOS Only
62TwilioVoice.addEventListener('callRejected', function(value: 'callRejected') {})
63
64TwilioVoice.addEventListener('deviceDidReceiveIncoming', function(data) {
65    // {
66    //     call_sid: string,  // Twilio call sid
67    //     call_from: string, // "+441234567890"
68    //     call_to: string,   // "client:bob"
69    // }
70})
71
72// Android Only
73TwilioVoice.addEventListener('proximity', function(data) {
74    // {
75    //     isNear: boolean
76    // }
77})
78
79// Android Only
80TwilioVoice.addEventListener('wiredHeadset', function(data) {
81    // {
82    //     isPlugged: boolean,
83    //     hasMic: boolean,
84    //     deviceName: string
85    // }
86})
87
88// ...
89
90// start a call
91TwilioVoice.connect({To: '+61234567890'})
92
93// hangup
94TwilioVoice.disconnect()
95
96// accept an incoming call (Android only, in iOS CallKit provides the UI for this)
97TwilioVoice.accept()
98
99// reject an incoming call (Android only, in iOS CallKit provides the UI for this)
100TwilioVoice.reject()
101
102// ignore an incoming call (Android only)
103TwilioVoice.ignore()
104
105// mute or un-mute the call
106// mutedValue must be a boolean
107TwilioVoice.setMuted(mutedValue)
108
109// put a call on hold
110TwilioVoice.hold(holdValue)
111
112// send digits
113TwilioVoice.sendDigits(digits)
114
115// Ensure that an active call is displayed when the app comes to foreground
116TwilioVoice.getActiveCall()
117    .then(activeCall => {
118        if (activeCall){
119            _displayActiveCall(activeCall)
120        }
121    })
122
123// Ensure that call invites are displayed when the app comes to foreground
124TwilioVoice.getCallInvite()
125    .then(callInvite => {
126        if (callInvite){
127            _handleCallInvite(callInvite)
128        }
129    })
130
131// Unregister device with Twilio (iOS only)
132TwilioVoice.unregister()

Help wanted

There is no need to ask permissions to contribute. Just open an issue or provide a PR. Everybody is welcome to contribute.

ReactNative success is directly linked to its module ecosystem. One way to make an impact is helping contributing to this module or another of the many community lead ones.

Twilio Voice SDK reference

iOS changelog Android changelog

Credits

voice-quickstart-android

voice-quickstart-ios

react-native-push-notification

License

MIT