Add Programmable Voice Participants to Video Rooms

The Programmable Video Rooms API allows you to add real-time voice and video into web, mobile, and desktop applications. With the Programmable Voice integration, you can connect PSTN (Public Switched Telephone Network) and SIP audio calls into your Video Rooms.

(information)

Info

Video Rooms can support up to 35 PSTN Participants.

(warning)

Warning

PSTN calls connecting to a Twilio Video Room will always be routed through the US-1 region, no matter where the call and phone number originates.

Working with Twilio Video Rooms in TwiML

Video Rooms are represented in TwiML through the <Room> noun within the <Connect> verb.

To connect a Programmable Voice call to a Video Room, use the <Room> noun and pass the unique name of the Room you would like to join within the TwiML.

1<?xml version="1.0" encoding="UTF‐8"?>
2<Response>
3  <Connect>
4    <Room>DailyStandup</Room>
5  </Connect>
6</Response>

If a room with that unique name does not exist for your account, the call will move to the next TwiML instruction, or disconnect if it is the last TwiML instruction.

Connect a Programmable Voice call to a Room

1const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3const response = new VoiceResponse();
4const connect = response.connect();
5connect.room('DailyStandup');
6
7console.log(response.toString());

Output

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Connect>
4    <Room>DailyStandup</Room>
5  </Connect>
6</Response>

Set the participant's identity

Video Rooms expect every Participant to have a unique identity. Every Programmable Voice Participant that joins a Video Room is considered to be a new Participant.

You can set a unique identity on the voice caller using the participantIdentity attribute on the <Room> noun. If a participantIdentity is not provided, Twilio will generate a random string and set it as the Participant's identity.

Connect a Programmable Voice call to a Room with a Participant identity

1const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3const response = new VoiceResponse();
4const connect = response.connect();
5connect.room({
6    participantIdentity: 'alice'
7}, 'DailyStandup');
8
9console.log(response.toString());

Output

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Connect>
4    <Room participantIdentity="alice">DailyStandup</Room>
5  </Connect>
6</Response>

(warning)

Warning

Twilio Video requires each Participant to have a unique identity. If two participants join a Programmable Video Room using the same identity, Twilio will disconnect the first participant with that identity and throw an error.

Connect incoming calls to a Video Room

The Programmable Voice documentation shows how to handle incoming voice calls. When a call comes in to your Twilio number, Twilio will send a webhook request to your web server to request TwiML instructions for the incoming call. To connect the incoming call to a Video Room, your web server should respond back with a TwiML response containing a <Room> noun, as shown above.

Make outgoing calls and connect them to a Video Room

The Programmable Voice documentation shows how to make outgoing calls. When you make an outbound call with your Twilio phone number, Twilio will send a webhook request to your web server when the called party answers the call and request TwiML instructions for handling the call. To connect the call to a Video Room, your web server should respond back with a TwiML response containing a <Room> noun, as shown above.

Known Issues

The <Connect> verb is designed to connect individual PSTN phone calls to a Video Room. This functionality should not be used to bridge a Programmable Voice Conference with a Video Room. This is an unsupported use case and it can fail in unexpected ways.