Skip to contentSkip to navigationSkip to topbar
On this page

Add Programmable Voice Participants to Video Rooms


(warning)

Warning

This documentation is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2026(link takes you to an external page).

We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.

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 Group Video Rooms.

(information)

Info

Only Group Rooms support PSTN Participants. Group 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

working-with-twilio-video-rooms-in-twiml page anchor

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 RoomLink to code sample: Connect a Programmable Voice call to a Room
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.room('DailyStandup');
6
7
console.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

set-the-participants-identity page anchor

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 identityLink to code sample: Connect a Programmable Voice call to a Room with a Participant identity
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.room({
6
participantIdentity: 'alice'
7
}, 'DailyStandup');
8
9
console.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

connect-incoming-calls-to-a-video-room page anchor

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

make-outgoing-calls-and-connect-them-to-a-video-room page anchor

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.


  • 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.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.