Menu

Expand
Rate this page:

Conversation Participant Resource

Each Participant in a Conversation represents one real (probably human) participant in a Conversation.

Creating a Participant joins them with the conversation, and the connected person will receive all subsequent messages.

Deleting a participant removes them from the conversation. They will receive no new messages after that point, but their previous messages will remain in the conversation.

API Base URL

All URLs in the reference documentation use the following base URL:

https://conversations.twilio.com/v1

Using the shortened base URL

Using the REST API, you can interact with Conversation Participant resources in the default Conversation Service instance via a "shortened" URL that does not include the Conversation Service instance SID ("ISXXX..."). If you are only using one Conversation Service (the default), you do not need to include the Conversation Service SID in your URL, e.g.

GET /v1/Conversations/CHxx/Participants

For Conversations applications that build on more than one Conversation Service instance, you will need to specify the Conversation Service SID in the REST API call:

GET /v1/Services/ISxx/Conversations/CHxx/Participants

ConversationParticipant properties

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

The unique ID of the Account responsible for this participant.

conversation_sid
sid<CH> Not PII

The unique ID of the Conversation for this participant.

sid
sid<MB> Not PII

A 34 character string that uniquely identifies this resource.

identity

A unique string identifier for the conversation participant as Conversation User. This parameter is non-null if (and only if) the participant is using the Conversations SDK to communicate. Limited to 256 characters.

attributes

An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned.

messaging_binding

Information about how this participant exchanges messages with the conversation. A JSON parameter consisting of type and address fields of the participant.

role_sid
sid<RL> Not PII

The SID of a conversation-level Role to assign to the participant.

date_created
date_time<iso8601> Not PII

The date that this resource was created.

date_updated
date_time<iso8601> Not PII

The date that this resource was last updated.

url
url Not PII

An absolute API resource URL for this participant.

last_read_message_index
integer? Not PII

Index of last “read” message in the Conversation for the Participant.

last_read_timestamp
string Not PII

Timestamp of last “read” message in the Conversation for the Participant.

Add a Conversation Participant (SMS)

post
https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Participants

Adding a new participant to an ongoing conversation immediately allows them to see all subsequent communications. The same person (i.e., a single personal phone number) can be part of any number of conversations concurrently, as long as the address they are in contact with (the ProxyAddress) is unique.

To create a Conversation Participant by SMS, you must enter:

  1. Their phone number as the messagingbinding.address
  2. Your Twilio number as the messagingbinding.proxyaddress.


To create a Conversation Participant by Chat, you must enter the Chat User Identity as the identity parameter.

We recommend following the standard URI specification and avoid the following reserved characters ! * ' ( ) ; : @ & = + $ , / ? % # [ ] for values such as identity and friendly name.

Parameters
Parameters in REST API format
conversation_sid
Path
post sid_like<CH> Not PII

The unique ID of the Conversation for this participant.

identity
Optional
post string PII MTL: 30 DAYS

A unique string identifier for the conversation participant as Conversation User. This parameter is non-null if (and only if) the participant is using the Conversations SDK to communicate. Limited to 256 characters.

messaging_binding.address
Optional
post string Not PII

The address of the participant's device, e.g. a phone or WhatsApp number. Together with the Proxy address, this determines a participant uniquely. This field (with proxy_address) is only null when the participant is interacting from an SDK endpoint (see the 'identity' field).

messaging_binding.proxy_address
Optional
post string Not PII

The address of the Twilio phone number (or WhatsApp number) that the participant is in contact with. This field, together with participant address, is only null when the participant is interacting from an SDK endpoint (see the 'identity' field).

date_created
Optional
post date_time<iso8601> Not PII

The date that this resource was created.

date_updated
Optional
post date_time<iso8601> Not PII

The date that this resource was last updated.

attributes
Optional
post string PII MTL: 30 DAYS

An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned.

messaging_binding.projected_address
Optional
post string Not PII

The address of the Twilio phone number that is used in Group MMS. Communication mask for the Conversation participant with Identity.

role_sid
Optional
post sid<RL> Not PII

The SID of a conversation-level Role to assign to the participant.

x_twilio_webhook_enabled
Header
post ienum:webhook_enabled_type Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Example 1
Loading Code Sample...
        
        
        Connect someone to a Conversation over SMS

        Create Conversation Participant (SMS)

        Connect someone to a Conversation over SMS
        Example 2
        Loading Code Sample...
              
              
              Connect someone to a Conversation over Chat

              Create Conversation Participant (Chat)

              Connect someone to a Conversation over Chat

              Fetch a ConversationParticipant resource

              get
              https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Participants/{Sid}
              Parameters
              Parameters in REST API format
              conversation_sid
              Path
              get sid_like<CH> Not PII

              The unique ID of the Conversation for this participant.

              sid
              Path
              get sid_like<MB> Not PII

              A 34 character string that uniquely identifies this resource. Alternatively, you can pass a Participant's identity rather than the SID.

              Example 1
              Loading Code Sample...
                    
                    
                    Fetch a Conversation Participant by SID

                    Fetch Conversation Participant by SID

                    Fetch a Conversation Participant by SID

                    You can also fetch a Conversation Participant by their identity. Pass their identity as the value for the sid argument.

                    Example 2
                    Loading Code Sample...
                          
                          
                          Fetch a Conversation Participant by identity

                          Fetch Conversation Participant by identity

                          Fetch a Conversation Participant by identity

                          Read multiple ConversationParticipant resources

                          get
                          https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Participants
                          Parameters
                          Parameters in REST API format
                          conversation_sid
                          Path
                          get sid_like<CH> Not PII

                          The unique ID of the Conversation for participants.

                          Example 1
                          Loading Code Sample...
                                
                                

                                List Conversation Participant(s)

                                Update a ConversationParticipant resource

                                post
                                https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Participants/{Sid}
                                Parameters
                                Parameters in REST API format
                                conversation_sid
                                Path
                                post sid_like<CH> Not PII

                                The unique ID of the Conversation for this participant.

                                sid
                                Path
                                post sid_like<MB> Not PII

                                A 34 character string that uniquely identifies this resource.

                                date_created
                                Optional
                                post date_time<iso8601> Not PII

                                The date that this resource was created.

                                date_updated
                                Optional
                                post date_time<iso8601> Not PII

                                The date that this resource was last updated.

                                attributes
                                Optional
                                post string PII MTL: 30 DAYS

                                An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned.

                                role_sid
                                Optional
                                post sid<RL> Not PII

                                The SID of a conversation-level Role to assign to the participant.

                                messaging_binding.proxy_address
                                Optional
                                post string Not PII

                                The address of the Twilio phone number that the participant is in contact with. 'null' value will remove it.

                                messaging_binding.projected_address
                                Optional
                                post string Not PII

                                The address of the Twilio phone number that is used in Group MMS. 'null' value will remove it.

                                identity
                                Optional
                                post string PII MTL: 30 DAYS

                                A unique string identifier for the conversation participant as Conversation User. This parameter is non-null if (and only if) the participant is using the Conversations SDK to communicate. Limited to 256 characters.

                                last_read_message_index
                                Optional
                                post integer? Not PII

                                Index of last “read” message in the Conversation for the Participant.

                                last_read_timestamp
                                Optional
                                post string Not PII

                                Timestamp of last “read” message in the Conversation for the Participant.

                                x_twilio_webhook_enabled
                                Header
                                post ienum:webhook_enabled_type Not PII

                                The X-Twilio-Webhook-Enabled HTTP request header

                                Example 1
                                Loading Code Sample...
                                      
                                      
                                      Update Conversation Participant by SID

                                      Update Conversation Participant

                                      Update Conversation Participant by SID
                                      Example 2
                                      Loading Code Sample...
                                            
                                            

                                            Update attributes for a Conversation Participant

                                            Delete a ConversationParticipant resource

                                            delete
                                            https://conversations.twilio.com/v1/Conversations/{ConversationSid}/Participants/{Sid}
                                            Parameters
                                            Parameters in REST API format
                                            conversation_sid
                                            Path
                                            delete sid_like<CH> Not PII

                                            The unique ID of the Conversation for this participant.

                                            sid
                                            Path
                                            delete sid_like<MB> Not PII

                                            A 34 character string that uniquely identifies this resource.

                                            x_twilio_webhook_enabled
                                            Header
                                            delete ienum:webhook_enabled_type Not PII

                                            The X-Twilio-Webhook-Enabled HTTP request header

                                            Example 1
                                            Loading Code Sample...
                                                  
                                                  
                                                  Delete a Conversation Participant by SID

                                                  Delete Conversation Participant

                                                  Delete a Conversation Participant by SID
                                                  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