Menu

Expand
Rate this page:

Conference Participant Resource

Twilio's Voice API Participant resource represents a participant who is actively connected to a given conference.

The Participant resource allows you to:

  • Manipulate a conference's current participants by muting or removing them from the conference
  • List of all the participants in an active conference
  • Get information about a particular participant in an active conference
  • Add participants to a Conference

Tracking updates to all conference participants over the course of a conference can be done by using the Conference's statusCallback webhook.

Participant properties

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

The SID of the Account that created the Participant resource.

call_sid
sid<CA> Not PII

The SID of the Call the Participant resource is associated with.

label
string Not PII

The user-specified label of this participant, if one was given when the participant was created. This may be used to fetch, update or delete the participant.

call_sid_to_coach
sid<CF> Not PII

The SID of the participant who is being coached. The participant being coached is the only participant who can hear the participant who is coaching.

coaching
boolean Not PII

Whether the participant is coaching another call. Can be: true or false. If not present, defaults to false unless call_sid_to_coach is defined. If true, call_sid_to_coach must be defined.

conference_sid
sid<CF> Not PII

The SID of the conference the participant is in.

date_created
date_time<rfc2822> Not PII

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

date_updated
date_time<rfc2822> Not PII

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

end_conference_on_exit
boolean Not PII

Whether the conference ends when the participant leaves. Can be: true or false and the default is false. If true, the conference ends and all other participants drop out when the participant leaves.

muted
boolean Not PII

Whether the participant is muted. Can be true or false.

hold
boolean Not PII

Whether the participant is on hold. Can be true or false.

start_conference_on_enter
boolean Not PII

Whether the conference starts when the participant joins the conference, if it has not already started. Can be: true or false and the default is true. If false and the conference has not started, the participant is muted and hears background music until another participant starts the conference.

status
enum:status Not PII

The status of the participant's call in a session. Can be: queued, connecting, ringing, connected, complete, or failed.

uri
uri Not PII

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

Create a Participant

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

Creates a Participant resource with either a ConferenceSid or FriendlyName initiates an outbound call and adds a new participant to the active Conference with that ConferenceSid or FriendlyName.

If an active conference does not exist with your FriendlyName, we create a new conference with that name and add the participant.

If a conference specified by ConferenceSid is not active, the request fails.

Please do not use personally identifiable information (PII) such as phone numbers, email addresses, a person's name, or any other sensitive information when assigning a FriendlyName to your conferences.

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

The SID of the Account that will create the resource.

conference_sid
Path
post sid_like<CF> Not PII

The SID of the participant's conference.

from
Required
post phone_number<e164> PII MTL: 120 DAYS

The phone number, Client identifier, or username portion of SIP address that made this call. Phone numbers are in E.164 format (e.g., +16175551212). Client identifiers are formatted client:name. If using a phone number, it must be a Twilio number or a Verified outgoing caller id for your account. If the to parameter is a phone number, from must also be a phone number. If to is sip address, this value of from should be a username portion to be used to populate the P-Asserted-Identity header that is passed to the SIP endpoint.

to
Required
post phone_number<e164> PII MTL: 120 DAYS

The phone number, SIP address, or Client identifier that received this call. Phone numbers are in E.164 format (e.g., +16175551212). SIP addresses are formatted as sip:name@company.com. Client identifiers are formatted client:name. Custom parameters may also be specified.

status_callback
Optional
post url Not PII

The URL we should call using the status_callback_method to send status information to your application.

status_callback_method
Optional
post http_method Not PII

The HTTP method we should use to call status_callback. Can be: GET and POST and defaults to POST.

status_callback_event
Optional
post string[] Not PII

The conference state changes that should generate a call to status_callback. Can be: initiated, ringing, answered, and completed. Separate multiple values with a space. The default value is completed.

label
Optional
post string Not PII

A label for this participant. If one is supplied, it may subsequently be used to fetch, update or delete the participant.

timeout
Optional
post integer Not PII

The number of seconds that we should allow the phone to ring before assuming there is no answer. Can be an integer between 5 and 600, inclusive. The default value is 60. We always add a 5-second timeout buffer to outgoing calls, so value of 10 would result in an actual timeout that was closer to 15 seconds.

record
Optional
post boolean Not PII

Whether to record the participant and their conferences, including the time between conferences. Can be true or false and the default is false.

muted
Optional
post boolean Not PII

Whether the agent is muted in the conference. Can be true or false and the default is false.

beep
Optional
post string Not PII

Whether to play a notification beep to the conference when the participant joins. Can be: true, false, onEnter, or onExit. The default value is true.

start_conference_on_enter
Optional
post boolean Not PII

Whether to start the conference when the participant joins, if it has not already started. Can be: true or false and the default is true. If false and the conference has not started, the participant is muted and hears background music until another participant starts the conference.

end_conference_on_exit
Optional
post boolean Not PII

Whether to end the conference when the participant leaves. Can be: true or false and defaults to false.

wait_url
Optional
post url Not PII

The URL we should call using the wait_method for the music to play while participants are waiting for the conference to start. The default value is the URL of our standard hold music. Learn more about hold music.

wait_method
Optional
post http_method Not PII

The HTTP method we should use to call wait_url. Can be GET or POST and the default is POST. When using a static audio file, this should be GET so that we can cache the file.

early_media
Optional
post boolean Not PII

Whether to allow an agent to hear the state of the outbound call, including ringing or disconnect messages. Can be: true or false and defaults to true.

max_participants
Optional
post integer Not PII

The maximum number of participants in the conference. Can be a positive integer from 2 to 250. The default value is 250.

conference_record
Optional
post string Not PII

Whether to record the conference the participant is joining. Can be: true, false, record-from-start, and do-not-record. The default value is false.

conference_trim
Optional
post string Not PII

Whether to trim leading and trailing silence from your recorded conference audio files. Can be: trim-silence or do-not-trim and defaults to trim-silence.

conference_status_callback
Optional
post url Not PII

The URL we should call using the conference_status_callback_method when the conference events in conference_status_callback_event occur. Only the value set by the first participant to join the conference is used. Subsequent conference_status_callback values are ignored.

conference_status_callback_method
Optional
post http_method Not PII

The HTTP method we should use to call conference_status_callback. Can be: GET or POST and defaults to POST.

conference_status_callback_event
Optional
post string[] Not PII

The conference state changes that should generate a call to conference_status_callback. Can be: start, end, join, leave, mute, hold, and speaker. Separate multiple values with a space. Defaults to start end.

recording_channels
Optional
post string Not PII

The recording channels for the final recording. Can be: mono or dual and the default is mono.

recording_status_callback
Optional
post url Not PII

The URL that we should call using the recording_status_callback_method when the recording status changes.

recording_status_callback_method
Optional
post http_method Not PII

The HTTP method we should use when we call recording_status_callback. Can be: GET or POST and defaults to POST.

sip_auth_username
Optional
post string Not PII

The SIP username used for authentication.

sip_auth_password
Optional
post string Not PII

The SIP password for authentication.

region
Optional
post string Not PII

The region where we should mix the recorded audio. Can be:us1, ie1, de1, sg1, br1, au1, or jp1.

conference_recording_status_callback
Optional
post url Not PII

The URL we should call using the conference_recording_status_callback_method when the conference recording is available.

conference_recording_status_callback_method
Optional
post http_method Not PII

The HTTP method we should use to call conference_recording_status_callback. Can be: GET or POST and defaults to POST.

recording_status_callback_event
Optional
post string[] Not PII

The recording state changes that should generate a call to recording_status_callback. Can be: in-progress, completed, and failed. Separate multiple values with a space. The default value is in-progress completed failed.

conference_recording_status_callback_event
Optional
post string[] Not PII

The conference recording state changes that generate a call to conference_recording_status_callback. Can be: in-progress, completed, and failed. Separate multiple values with a space. The default value is in-progress completed failed.

coaching
Optional
post boolean Not PII

Whether the participant is coaching another call. Can be: true or false. If not present, defaults to false unless call_sid_to_coach is defined. If true, call_sid_to_coach must be defined.

call_sid_to_coach
Optional
post sid<CA> Not PII

The SID of the participant who is being coached. The participant being coached is the only participant who can hear the participant who is coaching.

jitter_buffer_size
Optional
post string Not PII

Jitter buffer size for the connecting participant. Twilio will use this setting to apply Jitter Buffer before participant's audio is mixed into the conference. Can be: off, small, medium, and large. Default to large.

byoc
Optional
post sid<BY> Not PII

The SID of a BYOC (Bring Your Own Carrier) trunk to route this call with. Note that byoc is only meaningful when to is a phone number; it will otherwise be ignored. (Beta)

caller_id
Optional
post string Not PII

The phone number, Client identifier, or username portion of SIP address that made this call. Phone numbers are in E.164 format (e.g., +16175551212). Client identifiers are formatted client:name. If using a phone number, it must be a Twilio number or a Verified outgoing caller id for your account. If the to parameter is a phone number, callerId must also be a phone number. If to is sip address, this value of callerId should be a username portion to be used to populate the From header that is passed to the SIP endpoint.

call_reason
Optional
post string PII MTL: 120 DAYS

The Reason for the outgoing call. Use it to specify the purpose of the call that is presented on the called party's phone. (Branded Calls Beta)

recording_track
Optional
post string Not PII

The track to record. Can be: inbound, outbound, or both. The default is both. inbound only records the audio received by Twilio, outbound only records audio sent from Twilio, and both mixes the inbound and outbound audio.

Example 1
        
        
        
        
        Creates a Participant in a Conference. If this ConferenceSid is not an active conference, the request will fail.

        Create a Conference Participant

        Creates a Participant in a Conference. If this ConferenceSid is not an active conference, the request will fail.

        Only applies to Twilio Voice Client or SIP endpoints

        Custom parameters can be passed to the specified client id or SIP endpoint in the to field using query string notation, e.g.

        client:alice?mycustomparam1=foo&mycustomparam2=bar

        Fetch a Participant resource

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

        Returns a Participant resource from an active Conference, specified by the Conference SID and the Participant's Call SID or label.

        The Participant resource only manages active participants of in-progress Conferences.

        If you want to get a list of all conference participants over the course of a conference, use the Conference's statusCallback to receive webhooks for each participant joining the conference and store the details in your application.

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

        The SID of the Account that created the Participant resource to fetch.

        conference_sid
        Path
        get sid<CF> Not PII

        The SID of the conference with the participant to fetch.

        call_sid
        Path
        get sid_like<CA> Not PII

        The Call SID or label of the participant to fetch. Non URL safe characters in a label must be percent encoded, for example, a space character is represented as %20.

        Example 1
              
              
              
              
              Example 2
                    
                    
                    
                    

                    Read multiple Participant resources

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

                    Returns the list of active participants in the conference identified by {ConferenceSid}.

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

                    The SID of the Account that created the Participant resources to read.

                    conference_sid
                    Path
                    get sid<CF> Not PII

                    The SID of the conference with the participants to read.

                    muted
                    Optional
                    get boolean Not PII

                    Whether to return only participants that are muted. Can be: true or false.

                    hold
                    Optional
                    get boolean Not PII

                    Whether to return only participants that are on hold. Can be: true or false.

                    coaching
                    Optional
                    get boolean Not PII

                    Whether to return only participants who are coaching another call. Can be: true or false.

                    Example 1
                          
                          
                          
                          

                          Update a Participant resource

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

                          Updates the status of a participant in an active conference.

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

                          The SID of the Account that created the Participant resources to update.

                          conference_sid
                          Path
                          post sid<CF> Not PII

                          The SID of the conference with the participant to update.

                          call_sid
                          Path
                          post sid_like<CA> Not PII

                          The Call SID or label of the participant to update. Non URL safe characters in a label must be percent encoded, for example, a space character is represented as %20.

                          muted
                          Optional
                          post boolean Not PII

                          Whether the participant should be muted. Can be true or false. true will mute the participant, and false will un-mute them. Anything value other than true or false is interpreted as false.

                          hold
                          Optional
                          post boolean Not PII

                          Whether the participant should be on hold. Can be: true or false. true puts the participant on hold, and false lets them rejoin the conference.

                          hold_url
                          Optional
                          post url Not PII

                          The URL we call using the hold_method for music that plays when the participant is on hold. The URL may return an MP3 file, a WAV file, or a TwiML document that contains the <Play>, <Say> or <Redirect> commands.

                          hold_method
                          Optional
                          post http_method Not PII

                          The HTTP method we should use to call hold_url. Can be: GET or POST and the default is GET.

                          announce_url
                          Optional
                          post url Not PII

                          The URL we call using the announce_method for an announcement to the participant. The URL must return an MP3 file, a WAV file, or a TwiML document that contains <Play> or <Say> commands.

                          announce_method
                          Optional
                          post http_method Not PII

                          The HTTP method we should use to call announce_url. Can be: GET or POST and defaults to POST.

                          wait_url
                          Optional
                          post url Not PII

                          The URL we should call using the wait_method for the music to play while participants are waiting for the conference to start. The default value is the URL of our standard hold music. Learn more about hold music.

                          wait_method
                          Optional
                          post http_method Not PII

                          The HTTP method we should use to call wait_url. Can be GET or POST and the default is POST. When using a static audio file, this should be GET so that we can cache the file.

                          beep_on_exit
                          Optional
                          post boolean Not PII

                          Whether to play a notification beep to the conference when the participant exits. Can be: true or false.

                          end_conference_on_exit
                          Optional
                          post boolean Not PII

                          Whether to end the conference when the participant leaves. Can be: true or false and defaults to false.

                          coaching
                          Optional
                          post boolean Not PII

                          Whether the participant is coaching another call. Can be: true or false. If not present, defaults to false unless call_sid_to_coach is defined. If true, call_sid_to_coach must be defined.

                          call_sid_to_coach
                          Optional
                          post sid<CA> Not PII

                          The SID of the participant who is being coached. The participant being coached is the only participant who can hear the participant who is coaching.

                          Example 1
                                
                                
                                
                                
                                Example 2
                                      
                                      
                                      
                                      
                                      Example 3
                                            
                                            
                                            
                                            
                                            Example 4
                                                  
                                                  
                                                  
                                                  
                                                  Plays the audio file at the announce_url for the participant

                                                  Make an announcement to the participant

                                                  Plays the audio file at the announce_url for the participant

                                                  Delete a Participant resource

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

                                                  Deletes the Participant resource to remove the participant from the conference. Returns HTTP 204 (No Content) with no body if the participant was successfully removed from the conference.

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

                                                  The SID of the Account that created the Participant resources to delete.

                                                  conference_sid
                                                  Path
                                                  delete sid<CF> Not PII

                                                  The SID of the conference with the participants to delete.

                                                  call_sid
                                                  Path
                                                  delete sid_like<CA> Not PII

                                                  The Call SID or label of the participant to delete. Non URL safe characters in a label must be percent encoded, for example, a space character is represented as %20.

                                                  Example 1
                                                        
                                                        
                                                        
                                                        
                                                        Example 2
                                                              
                                                              
                                                              
                                                              
                                                              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 browsing the Twilio tag on Stack Overflow.

                                                                    
                                                                    
                                                                    

                                                                    Thank you for your feedback!

                                                                    We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

                                                                    Thanks for your feedback!

                                                                    Refer us and get $10 in 3 simple steps!

                                                                    Step 1

                                                                    Get link

                                                                    Get a free personal referral link here

                                                                    Step 2

                                                                    Give $10

                                                                    Your user signs up and upgrade using link

                                                                    Step 3

                                                                    Get $10

                                                                    1,250 free SMSes
                                                                    OR 1,000 free voice mins
                                                                    OR 12,000 chats
                                                                    OR more