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

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
string 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 endpoint 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 endpoint 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 the conference recording. 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, modify, speaker, and announcement. 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: started, in-progress, paused, resumed, stopped, completed, failed, and absent. Separate multiple values with a space, ex: '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, failed, and absent. Separate multiple values with a space, ex: '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 audio track to record for the call. Can be: inbound, outbound or both. The default is both. inbound records the audio that is received by Twilio. outbound records the audio that is sent from Twilio. both records the audio that is received and sent by Twilio.

time_limit
Optional
post integer Not PII

The maximum duration of the call in seconds. Constraints depend on account and configuration.

machine_detection
Optional
post string Not PII

Whether to detect if a human, answering machine, or fax has picked up the call. Can be: Enable or DetectMessageEnd. Use Enable if you would like us to return AnsweredBy as soon as the called party is identified. Use DetectMessageEnd, if you would like to leave a message on an answering machine. For more information, see Answering Machine Detection.

machine_detection_timeout
Optional
post integer Not PII

The number of seconds that we should attempt to detect an answering machine before timing out and sending a voice request with AnsweredBy of unknown. The default timeout is 30 seconds.

machine_detection_speech_threshold
Optional
post integer Not PII

The number of milliseconds that is used as the measuring stick for the length of the speech activity, where durations lower than this value will be interpreted as a human and longer than this value as a machine. Possible Values: 1000-6000. Default: 2400.

machine_detection_speech_end_threshold
Optional
post integer Not PII

The number of milliseconds of silence after speech activity at which point the speech activity is considered complete. Possible Values: 500-5000. Default: 1200.

machine_detection_silence_timeout
Optional
post integer Not PII

The number of milliseconds of initial silence after which an unknown AnsweredBy result will be returned. Possible Values: 2000-10000. Default: 5000.

amd_status_callback
Optional
post url Not PII

The URL that we should call using the amd_status_callback_method to notify customer application whether the call was answered by human, machine or fax.

amd_status_callback_method
Optional
post http_method Not PII

The HTTP method we should use when calling the amd_status_callback URL. Can be: GET or POST and the default is POST.

trim
Optional
post string Not PII

Whether to trim any leading and trailing silence from the participant recording. Can be: trim-silence or do-not-trim and the default is trim-silence.

call_token
Optional
post string Not PII

A token string needed to invoke a forwarded call. A call_token is generated when an incoming call is received on a Twilio number. Pass an incoming call's call_token value to a forwarded call via the call_token parameter when creating a new call. A forwarded call should bear the same CallerID of the original incoming call.

Example 1
Loading Code Sample...
        
        
        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.

        Answering Machine Detection on requires Enhanced Programmable SIP Features to be enabled on the account.

        Custom Parameters

        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
        Loading Code Sample...
              
              

              Fetch a Participant resource

              Example 2
              Loading Code Sample...
                    
                    

                    Fetch a Participant resource by label

                    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
                    Loading Code Sample...
                          
                          

                          Read multiple Participant resources

                          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 <Play>, <Say>, <Pause>, or <Redirect> verbs.

                          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 may return an MP3 file, a WAV file, or a TwiML document that contains <Play>, <Say>, <Pause>, or <Redirect> verbs.

                          announce_method
                          Optional
                          post http_method Not PII

                          The HTTP method 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 call using the wait_method for the music to play while participants are waiting for the conference to start. The URL may return an MP3 file, a WAV file, or a TwiML document that contains <Play>, <Say>, <Pause>, or <Redirect> verbs. 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...
                                
                                

                                Mute Participant

                                Example 2
                                Loading Code Sample...
                                      
                                      

                                      Mute Participant by label

                                      Example 3
                                      Loading Code Sample...
                                            
                                            

                                            Place a participant on hold with music

                                            Example 4
                                            Loading Code Sample...
                                                  
                                                  
                                                  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
                                                  Loading Code Sample...
                                                        
                                                        

                                                        Delete a Participant

                                                        Example 2
                                                        Loading Code Sample...
                                                              
                                                              

                                                              Delete a Participant by label

                                                              What's next?

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

                                                              Rate this page:

                                                              Need some help?

                                                              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                                              Loading Code Sample...
                                                                    
                                                                    
                                                                    

                                                                    Thank you for your feedback!

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

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

                                                                    Thanks for your feedback!

                                                                    thanks-feedback-gif