Menu

Expand
Rate this page:

Conference Resource

The Conference resource allows you to query and manage the state of conferences on your Twilio account.

Conference rooms are not directly created from the Programmable Voice API.

In order to create a new conference, you must use TwiML's <Dial> verb with the <Conference> noun. After a Conference instance has been created, you can access it by using the REST API.

For step-by-step instructions on how to write this TwiML and programmatically handle the conference, check out our guides on how to create conference calls using Twilio's supported helper libraries.

Conference properties

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that created this Conference resource.

date_created
date_time<rfc2822> Not PII

The date and time in GMT that this resource was created specified in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date and time in GMT that this resource was last updated, specified in RFC 2822 format.

api_version
string Not PII

The API version used to create this conference.

friendly_name
string Not PII

A string that you assigned to describe this conference room. Maxiumum length is 128 characters.

region
string Not PII

A string that represents the Twilio Region where the conference audio was mixed. May be us1, ie1, de1, sg1, br1, au1, and jp1. Basic conference audio will always be mixed in us1. Global Conference audio will be mixed nearest to the majority of participants.

sid
sid<CF> Not PII

The unique string that that we created to identify this Conference resource.

status
enum:status Not PII

The status of this conference. Can be: init, in-progress, or completed.

uri
string Not PII

The URI of this resource, relative to https://api.twilio.com.

subresource_uris
uri_map Not PII

A list of related resources identified by their URIs relative to https://api.twilio.com.

reason_conference_ended
enum:reason_conference_ended Not PII

The reason why a conference ended. When a conference is in progress, will be null. When conference is completed, can be: conference-ended-via-api, participant-with-end-conference-on-exit-left, participant-with-end-conference-on-exit-kicked, last-participant-kicked, or last-participant-left.

call_sid_ending_conference
sid<CA> Not PII

The call SID that caused the conference to end.

You may have many conference instances that share the same friendly_name. Only one of these distinct conferences may be in-progress at any given time. For instance, if you have two separate conferences with the friendly_name of "my-conference" you cannot add participants to one instance while the other is in progress.

Fetch a Conference resource

get
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{Sid}.json

The recommended way to monitor the state of a Conference and its participants is to use the Conference statusCallback. This webhook callback will be fired when the state of the Conference or a participant changes.

At any time you can use the REST API to query the Conference and Participant resources, however continuously polling these resources is not recommended.

Please also note that when fetching conferences after the conference has ended, associated participant subresources will not be returned. For fetching conference participants after a conference has ended, please see the Voice Insights Conference Summary resource.

Parameters
Parameters in REST API format
account_sid
Path
get sid<AC> Not PII

The SID of the Account that created the Conference resource(s) to fetch.

sid
Path
get sid<CF> Not PII

The Twilio-provided string that uniquely identifies the Conference resource to fetch

Example 1
Loading Code Sample...
        
        

        Fetch a Conference resource

        Read multiple Conference resources

        get
        https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences.json

        Read all the conferences within your account.

        The list of conferences that we return includes paging information.

        Parameters
        Parameters in REST API format
        account_sid
        Path
        get sid<AC> Not PII

        The SID of the Account that created the Conference resource(s) to read.

        date_created
        Optional
        get date_inequality<iso8601> Not PII

        The date_created value, specified as YYYY-MM-DD, of the resources to read. To read conferences that started on or before midnight on a date, use <=YYYY-MM-DD, and to specify conferences that started on or after midnight on a date, use >=YYYY-MM-DD.

        date_updated
        Optional
        get date_inequality<iso8601> Not PII

        The date_updated value, specified as YYYY-MM-DD, of the resources to read. To read conferences that were last updated on or before midnight on a date, use <=YYYY-MM-DD, and to specify conferences that were last updated on or after midnight on a given date, use >=YYYY-MM-DD.

        friendly_name
        Optional
        get string Not PII

        The string that identifies the Conference resources to read.

        status
        Optional
        get enum:status Not PII

        The status of the resources to read. Can be: init, in-progress, or completed.

        Example 1
        Loading Code Sample...
              
              
              Returns the list of all Conferences in the account

              Read multiple Conference resources

              Returns the list of all Conferences in the account
              Example 2
              Loading Code Sample...
                    
                    
                    Returns a list of conferences that started on July 07, 2020

                    Read the conferences that started on a specific date

                    Returns a list of conferences that started on July 07, 2020
                    Example 3
                    Loading Code Sample...
                          
                          
                          Returns a list of in-progress conferences that started on or after midnight on January 1, 2021

                          Read the in-progress conferences that were created on or after a specific date

                          Returns a list of in-progress conferences that started on or after midnight on January 1, 2021
                          Example 4
                          Loading Code Sample...
                                
                                
                                Returns the conferences named "MyRoom"

                                Read the conferences named "MyRoom"

                                Returns the conferences named "MyRoom"

                                Update a Conference resource

                                post
                                https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{Sid}.json

                                You can use the update action to change the conference's properties as well as to end the conference.

                                Parameters
                                Parameters in REST API format
                                account_sid
                                Path
                                post sid<AC> Not PII

                                The SID of the Account that created the Conference resource(s) to update.

                                sid
                                Path
                                post sid_like<CF> Not PII

                                The Twilio-provided string that uniquely identifies the Conference resource to update

                                status
                                Optional
                                post enum:update_status Not PII

                                The new status of the resource. Can be: Can be: init, in-progress, or completed. Specifying completed will end the conference and hang up all participants

                                announce_url
                                Optional
                                post url Not PII

                                The URL we should call to announce something into the conference. The URL may return an MP3 file, a WAV file, or a TwiML document that contains <Play>, <Say>, <Pause>, or <Redirect> verbs.

                                announce_method
                                Optional
                                post http_method Not PII

                                The HTTP method used to call announce_url. Can be: GET or POST and the default is POST

                                Example 1
                                Loading Code Sample...
                                      
                                      
                                      End this conference by setting its status to 'completed'

                                      Update a conference to end it

                                      End this conference by setting its status to 'completed'
                                      Example 2
                                      Loading Code Sample...
                                            
                                            
                                            Include the AnnounceUrl parameter to play something for your conference participants

                                            Update a conference to announce something

                                            Include the AnnounceUrl parameter to play something for your conference participants

                                            Manage conference participants

                                            Each Conference has a Participants subresource. Participants represent the set of people currently connected to a running conference.

                                            You can request all participants from a given Conference by requesting the following:

                                            GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Participants.json

                                            See the full Participant API reference documentation for Participant properties, parameters, and actions.

                                            Conference Recordings

                                            You can access the Recordings list subresource on any given Conference.

                                            The following will return a list of all of the recordings generated for a given conference, identified by its ConferenceSid. (Note that recordings associated with an individual call leg of the conference will not be returned.)

                                            GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings.json

                                            See the Recordings reference documentation for resource properties and response formats.

                                            Conference Log Retention

                                            Starting on February 5, 2021 you will be able to retrieve resources via GET to the /Conferences and /Participants endpoints for thirteen months after the resource is created. This represents a significant change as these logs are currently stored indefinitely by Twilio and retrievable via Console and API.

                                            It's important to note that we are not deleting your logs, just changing where they will be available to you. We provide a Bulk Export utility in Console for Conferences and Participant resources, as well as an API. Bulk Export will generate S3 files containing one day of data per file and deliver the download link via webhook, email, or Console. Records older than thirteen months will only be able to be retrieved via Bulk Export.

                                            If you perform log extraction via API on a rolling basis, it is important to verify that you are pulling the logs at a frequency that will remain unaffected by this change.

                                            What's next?

                                            Explore Voice Insights with its Conference Insights Event Stream and Conference Insights REST API which allow you to see conference parameters, investigate participant event timelines, and understand detected quality issues.

                                            Rate this page:

                                            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.

                                            Loading Code Sample...
                                                  
                                                  
                                                  

                                                  Thank you for your feedback!

                                                  Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                  Sending your feedback...
                                                  🎉 Thank you for your feedback!
                                                  Something went wrong. Please try again.

                                                  Thanks for your feedback!

                                                  thanks-feedback-gif