Programmable Voice

Programmable Voice

Operational

Menu

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

Participant properties

account_sid
sid<AC> Not PII

The unique id of the Account that created this conference
call_sid
sid<CA> Not PII

A 34 character string that uniquely identifies the Participant call that is connected to this conference
conference_sid
sid<CF> Not PII

A 34 character string that identifies the conference this participant is in
date_created
date_time<rfc2822> Not PII

The date that this resource was created, in RFC 2822 format.
date_updated
date_time<rfc2822> Not PII

The date that this resource was last updated, in RFC 2822 format.
end_conference_on_exit
boolean Not PII

Indicates whether the endConferenceOnExit attribute was set on this participant, either true or false.
hold
boolean Not PII

true if this participant is currently on hold. false otherwise.
muted
boolean Not PII

true if this participant is currently muted. false otherwise.
start_conference_on_enter
boolean Not PII

Indicates whether the startConferenceOnEnter attribute was set on this participant, either true or false.
uri
uri Not PII

The URI for this 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
AccountSid
Required
post sid<AC> Not PII

The unique id of the Account that created this conference
ConferenceSid
Required
post sid_like<CF> Not PII

The string that uniquely identifies the conference this participant is in.
From
Required
post phone_number<e164> Not PII

The from phone number that will dial the new conference participant. Values may be a phone number or client id.
To
Required
post phone_number<e164> Not PII

The phone number, client id, or sip address you are inviting to this conference.
Beep
Optional
post string Not PII

Play a notification beep to the conference when this participant joins. Options are true, false, onEnter, or onExit. Defaults to true.
ConferenceRecord
Optional
post string Not PII

Records the conference that this participant is joining. Options are true, false, record-from-start, and do-not-record. Deafults to false
ConferenceRecordingStatusCallback
Optional
post url Not PII

The absolute URL Twilio should request when the conference recording is available.
ConferenceRecordingStatusCallbackEvent
Optional
post string[] Not PII

Specifies which conference recording state changes should generate a webhook to the URL specified in the ConferenceRecordingStatusCallback attribute. Available values are in-progress, completed, failed. To specify multiple values, separate them with a space. Defaults to in-progress, completed, failed.
ConferenceRecordingStatusCallbackMethod
Optional
post http_method Not PII

The HTTP method Twilio should use when requesting your recording status callback URL, either GET or POST. Defaults to POST.
ConferenceStatusCallback
Optional
post url Not PII

The absolute URL Twilio should request with conference events specified in ConferenceStatusCallbackEvent. This value is set by the first Participant to join the conference, and subsequent callback URLs will be ignored.
ConferenceStatusCallbackEvent
Optional
post string[] Not PII

Specifies which conference state changes should generate a webhook to the URL specified in the ConferenceStatusCallback attribute. Available values are start, end, join, leave, mute, hold, and speaker. To specify multiple values, separate them with a space. Defaults to start and end.
ConferenceStatusCallbackMethod
Optional
post http_method Not PII

The HTTP method Twilio should use when requesting the ConferenceStatusCallback URL. Either GET or POST. Defaults to POST.
ConferenceTrim
Optional
post string Not PII

Specify whether to trim leading and trailing silence from your recorded conference audio files. Options are trim-silence and do-not-trim. Defaults to trim-silence
EarlyMedia
Optional
post boolean Not PII

Allow an agent to hear the state of the outbound call, including ringing or disconnect messages. Can be true or false. Defaults to true.
EndConferenceOnExit
Optional
post boolean Not PII

If true, will end the conference when this participant leaves. Defaults to false.
MaxParticipants
Optional
post integer Not PII

The maximum number of participants within this agent conference. Values can be positive integers from 2-10. Defaults to 10.
Muted
Optional
post boolean Not PII

Specify whether the agent can speak in the conference. Values can be true or false. Defaults to false.
Record
Optional
post boolean Not PII

Records the agent and their conferences, including downtime between conferences. Values may be true or false. Defaults to false.
RecordingChannels
Optional
post string Not PII

Set the recording channels for the final agent/conference recording. Either mono or dual. Defaults to mono.
RecordingStatusCallback
Optional
post url Not PII

Specifies the absolute URL that Twilio should request when the recording is available if the agent and conference are recorded.
RecordingStatusCallbackEvent
Optional
post string[] Not PII

Specifies which recording state changes should generate a webhook to the URL specified in the RecordingStatusCallback attribute. Available values are in-progress, completed, failed. To specify multiple values, separate them with a space. Defaults to in-progress, completed, failed.
RecordingStatusCallbackMethod
Optional
post http_method Not PII

The HTTP method Twilio should use when requesting the RecordingStatusCallback. GET or POST. Defaults to POST.
Region
Optional
post string Not PII

Specifies the region where Twilio should mix the recorded audio. Options are us1, ie1, de1, sg1, br1, au1, jp1.
SipAuthPassword
Optional
post string Not PII

SIP password for authentication.
SipAuthUsername
Optional
post string Not PII

SIP username used for authenticating.
StartConferenceOnEnter
Optional
post boolean Not PII

If the conference has not already begun, true will start the conference when this participant joins. Specifying false will mute the participant and play background music until the conference begins. Defaults to true.
StatusCallback
Optional
post url Not PII

The absolute URL where Twilio should send a webhook with conference event information that you request with the StatusCallbackEvent parameter.
StatusCallbackEvent
Optional
post string[] Not PII

Specifies which conference state changes should generate a webhook to the StatusCallback URL. Options are initiated, ringing, answered, and completed. To specify multiple values, separate each with a space. Defaults to completed.
StatusCallbackMethod
Optional
post http_method Not PII

The method Twilio should use when requesting your StatusCallback URL. Options are GET and POST. Defaults to POST.
Timeout
Optional
post integer Not PII

The number of seconds (integer) that Twilio should allow the phone to ring before assuming there is no answer. Defaults to 60 seconds. Minimum allowed timeout is 5, max is 600. Twilio always adds a 5-second timeout buffer to outgoing calls, so if you enter a timeout value of 10 seconds, you will see an actual timeout closer to 15 seconds.
WaitMethod
Optional
post http_method Not PII

Specify which method, GET or POST, Twilio should use to request the WaitUrl for this conference. Be sure to use GET if you are directly requesting static audio files so that Twilio properly caches the files. Defaults to POST.
WaitUrl
Optional
post url Not PII

Specify an absolute URL that hosts music to play before the conference starts. Defualts to Twilio's standard hold music.
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
      

      


      

AccountSid

      Required
      
      		


      
get
sid<AC>
Not PII

      

      

      The unique id of the Account that created this conference
      

      
      		

      

      

CallSid

      Required
      
      		


      
get
sid<CA>
Not PII

      

      

      The Participant's unique Call SID.
      

      
      		

      

      

ConferenceSid

      Required
      
      		


      
get
sid<CF>
Not PII

      

      

      The string that uniquely identifies the conference this participant is in.
      

      
      		

      
      

      

      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
          

          


          

AccountSid

          Required
          
          		


          
get
sid<AC>
Not PII

          

          

          The unique id of the Account that created this conference
          

          
          		

          

          

ConferenceSid

          Required
          
          		


          
get
sid<CF>
Not PII

          

          

          The string that uniquely identifies the conference this participant is in.
          

          
          		

          

          

Hold

          Optional
          
          		


          
get
boolean
Not PII

          

          

          Only return participants that are on hold or not on hold. Either true or false.
          

          
          		

          

          

Muted

          Optional
          
          		


          
get
boolean
Not PII

          

          

          Only return participants that are muted or unmuted. Either 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
              

              


              

AccountSid

              Required
              
              		


              
post
sid<AC>
Not PII

              

              

              The unique id of the Account that created this conference
              

              
              		

              

              

CallSid

              Required
              
              		


              
post
sid<CA>
Not PII

              

              

              The Call SID that uniquely identifies this Participant.
              

              
              		

              

              

ConferenceSid

              Required
              
              		


              
post
sid<CF>
Not PII

              

              

              The string that uniquely identifies the conference this participant is in.
              

              
              		

              

              

AnnounceMethod

              Optional
              
              		


              
post
http_method
Not PII

              

              

              Specify the HTTP method Twilio should use to request your AnnounceUrl, either GET or POST. Defaults to POST.
              

              
              		

              

              

AnnounceUrl

              Optional
              
              		


              
post
url
Not PII

              

              

              The 'AnnounceUrl' attribute lets you specify a URL for announcing something to the participant. The URL may return an MP3, a WAV or a TwiML document with <Play> or <Say>.
              

              
              		

              

              

Hold

              Optional
              
              		


              
post
boolean
Not PII

              

              

              Specifying true will hold the participant, while false will remove them from hold.
              

              
              		

              

              

HoldMethod

              Optional
              
              		


              
post
http_method
Not PII

              

              

              Specify the HTTP method Twilio should use to request your HoldUrl, either GET or POST. Defaults to GET.
              

              
              		

              

              

HoldUrl

              Optional
              
              		


              
post
url
Not PII

              

              

              The 'HoldUrl' attribute lets you specify a URL for music that plays when a participant is on hold. The URL may be an MP3, a WAV or a TwiML document that uses <Play>, <Say> or <Redirect>.
              

              
              		

              

              

Muted

              Optional
              
              		


              
post
boolean
Not PII

              

              

              Specifying true will mute the participant, while false will un-mute. Anything other than true or false is interpreted as false.
              

              
              		

              
              

              

              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
                          

                          


                          

AccountSid

                          Required
                          
                          		


                          
delete
sid<AC>
Not PII

                          

                          

                          The unique id of the Account that created this conference
                          

                          
                          		

                          

                          

CallSid

                          Required
                          
                          		


                          
delete
sid<CA>
Not PII

                          

                          

                          The Call Sid that uniquely identifies this Participant.
                          

                          
                          		

                          

                          

ConferenceSid

                          Required
                          
                          		


                          
delete
sid<CF>
Not PII

                          

                          

                          The string that uniquely identifies the conference this participant is in.
                          

                          
                          		

                          
                          

                          

                          Example
                          

                          

                          

                          

                          

                          

                          


                          Loading Code Sample...
                          

                          
                          

                          

                            

                              

                              

                              

                              

                              








                              

                              

                              
Next Sample

                              

                              
Show Output

                              

                              


                              


                              

                              

                              

                              

                              

                              

                              

                              

                              

                              

                              
Delete Participant

                              

                              

                              

                              

                              

                              

                              

                              

                              

                              

                              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