Service-Scoped Conversation Participant Resource
Each service-scoped Participant in a Conversation represents one real (probably human) participant in a non-default, service-scoped Conversation.
API Base URL
All URLs in the reference documentation use the following base URL:
https://conversations.twilio.com/v1
For Conversations applications that build on more than one Conversation Service instance, you will need to specify the Conversation Service SID (ISxx) and the Conversation SID (CHxx) in the REST API call:
GET /v1/Services/ISxx/Conversations/CHxx/Messages
Service-Scoped Conversation Participant Properties
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The unique ID of the Account responsible for this participant. |
chat_service_sid
|
The SID of the Conversation Service the Participant resource is associated with. |
conversation_sid
|
The unique ID of the Conversation for this participant. |
sid
|
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 Conversation 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 |
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
|
The SID of a conversation-level Role to assign to the participant. |
date_created
|
The date on which this resource was created. |
date_updated
|
The date on which this resource was last updated. |
url
|
An absolute API resource URL for this participant. |
last_read_message_index
|
Index of last “read” message in the Conversation for the Participant. |
last_read_timestamp
|
Timestamp of last “read” message in the Conversation for the Participant. |
Create a Service-Scoped Participant resource
https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants
Creating a Participant joins them to the Conversation, and the connected person will receive all subsequent messages.
Parameters
| Parameters in REST API format | |
|---|---|
chat_service_sid
Path
|
The SID of the Conversation Service the Participant resource is associated with. |
conversation_sid
Path
|
The unique ID of the Conversation for this participant. |
identity
Optional
|
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 Conversation SDK to communicate. Limited to 256 characters. |
messaging_binding.address
Optional
|
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 |
messaging_binding.proxy_address
Optional
|
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 |
date_created
Optional
|
The date on which this resource was created. |
date_updated
Optional
|
The date on which this resource was last updated. |
attributes
Optional
|
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 |
messaging_binding.projected_address
Optional
|
The address of the Twilio phone number that is used in Group MMS. |
role_sid
Optional
|
The SID of a conversation-level Role to assign to the participant. |
x_twilio_webhook_enabled
Header
|
The X-Twilio-Webhook-Enabled HTTP request header |
Example 1
Fetch a Service-Scoped Participant resource
https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
chat_service_sid
Path
|
The SID of the Conversation Service the Participant resource is associated with. |
conversation_sid
Path
|
The unique ID of the Conversation for this participant. |
sid
Path
|
A 34 character string that uniquely identifies this resource. Alternatively, you can pass a Participant's |
Example 1
You can also fetch a Service-Scoped Conversation Participant by their identity. Pass their identity as the value for the sid argument.
Example 2
Read multiple Service-Scoped Participant resources
https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants
Parameters
| Parameters in REST API format | |
|---|---|
chat_service_sid
Path
|
The SID of the Conversation Service the Participant resource is associated with. |
conversation_sid
Path
|
The unique ID of the Conversation for participants. |
Example 1
Update a Service-Scoped Participant resource
https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
chat_service_sid
Path
|
The SID of the Conversation Service the Participant resource is associated with. |
conversation_sid
Path
|
The unique ID of the Conversation for this participant. |
sid
Path
|
A 34 character string that uniquely identifies this resource. |
date_created
Optional
|
The date on which this resource was created. |
date_updated
Optional
|
The date on which this resource was last updated. |
identity
Optional
|
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 Conversation SDK to communicate. Limited to 256 characters. |
attributes
Optional
|
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 |
role_sid
Optional
|
The SID of a conversation-level Role to assign to the participant. |
messaging_binding.proxy_address
Optional
|
The address of the Twilio phone number that the participant is in contact with. 'null' value will remove it. |
messaging_binding.projected_address
Optional
|
The address of the Twilio phone number that is used in Group MMS. 'null' value will remove it. |
last_read_message_index
Optional
|
Index of last “read” message in the Conversation for the Participant. |
last_read_timestamp
Optional
|
Timestamp of last “read” message in the Conversation for the Participant. |
x_twilio_webhook_enabled
Header
|
The X-Twilio-Webhook-Enabled HTTP request header |
Example 1
Delete a Service-Scoped Conversation Participant resource
https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants/{Sid}
Deleting a participant removes them from the Coonversation; they will receive no new messages after that point.
Parameters
| Parameters in REST API format | |
|---|---|
chat_service_sid
Path
|
The SID of the Conversation Service the Participant resource is associated with. |
conversation_sid
Path
|
The unique ID of the Conversation for this participant. |
sid
Path
|
A 34 character string that uniquely identifies this resource. |
x_twilio_webhook_enabled
Header
|
The X-Twilio-Webhook-Enabled HTTP request header |
Example 1
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.
