Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now
Programmable Voice

Twilio

Menu

Expand
Rate this page:

Thanks for rating this page!

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

Conference Participant

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

The Participant resource allows you to:

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

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

Participant properties

Names in PHP format
accountSid
sid<AC> Not PII

The SID of the Account that created the Participant resource.
callSid
sid<CA> Not PII

The SID of the Call the Participant resource is associated with.
callSidToCoach
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.
conferenceSid
sid<CF> Not PII

The SID of the conference the participant is in.
dateCreated
date_time<rfc2822> Not PII

The date and time in GMT that the resource was created specified in RFC 2822 format.
dateUpdated
date_time<rfc2822> Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822 format.
endConferenceOnExit
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.
startConferenceOnEnter
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 – Agent Conference only

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

Posting to the Participants list with either a ConferenceSid or FriendlyName will initiate an outbound call and add a new participant to the active Agent Conference with that ConferenceSid or FriendlyName.

Twilio's Agent Conference provides advanced features for building applications where agents speak with customers. You can enable Agent Conference on your Twilio account via the console.

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

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

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
Names in None format
account_sid
Required
post sid<AC> Not PII

The SID of the Account that will create the resource.
conference_sid
Required
post sid_like<CF> Not PII

The SID of the participant's conference.
from
Required
post phone_number<e164> PII MTL: 120 DAYS

The from phone number that will dial the new conference participant. Can be a phone number or a client id.
to
Required
post phone_number<e164> PII MTL: 120 DAYS

The phone number, client id, or sip address to invite to the conference.
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.
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.
Example 1
Loading Code Sample...
 
        

        
Next Sample

        

        
Show Output

        

        


        


        

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

        

        

        

        

        

        

        

        
Create Agent Conference Participant

        

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

        

        

        

        

        

        

        

        

        Fetch a Participant resource
        

        

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

        

        

        Return a Participant in an active Conference, specified by the Conference SID and the Participant's Call SID.
        

        

        

        

        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
        

        


        Names in None format
        
        


        

account_sid

        Required
        
        		


        
get
sid<AC>
Not PII

        

        

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

        
        		

        

        

conference_sid

        Required
        
        		


        
get
sid<CF>
Not PII

        

        

        The SID of the conference with the participant to fetch.
        

        
        		

        

        

call_sid

        Required
        
        		


        
get
sid<CA>
Not PII

        

        

        The Call SID of the resource to fetch.
        

        
        		

        
        

        

        Example
        

        

        

        

        

        

        

        


        Loading Code Sample...
        

        
        

        

          

          

            

              

              

              

              

              








              

              

              
Next Sample

              

              
Show Output

              

              


              


              

              

              

              

              

              

              

              

              

              

              
Fetch Participant

              

              

              

              

              

              

              

              

              

              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
              

              


              Names in None format
              
              


              

account_sid

              Required
              
              		


              
get
sid<AC>
Not PII

              

              

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

              
              		

              

              

conference_sid

              Required
              
              		


              
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
              

              

              

              

              

              

              

              


              Loading Code Sample...
              

              
              

              

                

                

                  

                    

                    

                    

                    

                    








                    

                    

                    
Next Sample

                    

                    
Show Output

                    

                    


                    


                    

                    

                    

                    

                    

                    

                    

                    

                    

                    

                    
Read: retrieve all participants

                    

                    

                    

                    

                    

                    

                    

                    

                    

                    Update a Participant resource
                    

                    

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

                    

                    

                    Update the status of a participant in an active conference.
                    

                    

                    Parameters
                    

                    


                    Names in None format
                    
                    


                    

account_sid

                    Required
                    
                    		


                    
post
sid<AC>
Not PII

                    

                    

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

                    
                    		

                    

                    

conference_sid

                    Required
                    
                    		


                    
post
sid<CF>
Not PII

                    

                    

                    The SID of the conference with the participant to update.
                    

                    
                    		

                    

                    

call_sid

                    Required
                    
                    		


                    
post
sid<CA>
Not PII

                    

                    

                    The Call SID of the resources to update.
                    

                    
                    		

                    

                    

muted

                    Optional
                    
                    		


                    
post
boolean
Not PII

                    

                    

                    Whether the participant should be muted. Can be true or false.truewill mute the participant, andfalsewill un-mute them. Anything value other thantrueorfalseis interpreted asfalse`.
                    

                    
                    		

                    

                    

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
                    

                    

                    

                    

                    

                    

                    

                    


                    Loading Code Sample...
                    

                    
                    

                    

                      

                      

                        

                          

                          

                          

                          

                          








                          

                          

                          
Next Sample

                          

                          
Show Output

                          

                          


                          


                          

                          

                          

                          

                          

                          

                          

                          

                          

                          

                          
Update: mute a participant

                          

                          

                          

                          

                          

                          

                          

                          Example 2
                          

                          

                          

                          

                          

                          

                          

                          


                          Loading Code Sample...
                          

                          
                          

                          

                            

                            

                              

                                

                                

                                

                                

                                








                                

                                

                                
Next Sample

                                

                                
Show Output

                                

                                


                                


                                

                                

                                

                                

                                

                                

                                

                                

                                

                                

                                
Update: Place a participant on hold with music

                                

                                

                                

                                

                                

                                

                                

                                Example 3
                                

                                

                                

                                

                                

                                

                                

                                


                                Loading Code Sample...
                                

                                
                                

                                

                                  

                                  

                                    

                                      

                                      

                                      

                                      

                                      








                                      

                                      

                                      
Next Sample

                                      

                                      
Show Output

                                      

                                      


                                      


                                      

                                      
      Plays the audio file at the announce_url for the participant
    
                                      

                                      

                                      

                                      

                                      

                                      

                                      

                                      

                                      
Update: 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

                                      

                                      

                                      Delete the Participant resource to kick this participant from the conference. Returns HTTP 204 (No Content) with no body if the participant was successfully booted from the conference.
                                      

                                      

                                      Parameters
                                      

                                      


                                      Names in None format
                                      
                                      


                                      

account_sid

                                      Required
                                      
                                      		


                                      
delete
sid<AC>
Not PII

                                      

                                      

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

                                      
                                      		

                                      

                                      

conference_sid

                                      Required
                                      
                                      		


                                      
delete
sid<CF>
Not PII

                                      

                                      

                                      The SID of the conference with the participants to delete.
                                      

                                      
                                      		

                                      

                                      

call_sid

                                      Required
                                      
                                      		


                                      
delete
sid<CA>
Not PII

                                      

                                      

                                      The Call SID of the resources to delete.
                                      

                                      
                                      		

                                      
                                      

                                      

                                      Example
                                      

                                      

                                      

                                      

                                      

                                      

                                      

                                      


                                      Loading Code Sample...
                                      

                                      
                                      

                                      

                                        

                                        

                                          

                                            

                                            

                                            

                                            

                                            








                                            

                                            

                                            
Next Sample

                                            

                                            
Show Output

                                            

                                            


                                            


                                            

                                            

                                            

                                            

                                            

                                            

                                            

                                            

                                            

                                            

                                            
Delete Participant

                                            

                                            

                                            

                                            

                                            

                                            

                                            

                                            

                                            

                                            





                                            
Rate this page:

                                              

                                            1. 

                                            2. 

                                            3. 

                                            4. 

                                            5. 

                                            

                                            

                                            

                                            

                                            

                                            

                                            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.
                                            

                                            

                                            


                                            

                                            

                                            

                                            

                                            

                                            


                                            Loading Code Sample...
                                            

                                            
                                            


                                            

                                              

                                              

                                                

                                                  

                                                  

                                                  

                                                  

                                                  








                                                  

                                                  

                                                  
Next Sample