Add Programmable Voice Participants to Video Rooms
This page 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, 2024.
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.
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.
<?xml version="1.0" encoding="UTF‐8"?>
<Response>
<Connect>
<Room>DailyStandup</Room>
</Connect>
</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.
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.
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 webserver to request TwiML instructions for the incoming call. To connect the incoming call to a Video Room, your webserver 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 webserver when the called party answers the call and request TwiML instructions for handling the call. To connect the call to a Video Room, your webserver 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.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
