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.
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide 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.
Only Group Rooms support PSTN Participants. Group Rooms can support up to 35 PSTN Participants.
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.
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.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;23const response = new VoiceResponse();4const connect = response.connect();5connect.room('DailyStandup');67console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Connect>4<Room>DailyStandup</Room>5</Connect>6</Response>
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.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;23const response = new VoiceResponse();4const connect = response.connect();5connect.room({6participantIdentity: 'alice'7}, 'DailyStandup');89console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Connect>4<Room participantIdentity="alice">DailyStandup</Room>5</Connect>6</Response>
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.
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.
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.
<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.