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 10. The default value is 10.

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

              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
                    
                    
                    
                    

                    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
                          
                          
                          
                          
                          Example 2
                                
                                
                                
                                
                                Example 3
                                      
                                      
                                      
                                      
                                      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
                                            
                                            
                                            
                                            
                                            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.