On this page

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:


_10https://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:


_10GET /v1/Services/ISxx/Conversations/CHxx/Messages

Service-Scoped Conversation Participant Properties

Resource properties

account_sidtype: SID<AC>Not PII

The unique ID of the Account responsible for this participant.

chat_service_sidtype: SID<IS>Not PII

The SID of the Conversation Service the Participant resource is associated with.

conversation_sidtype: SID<CH>Not PII

The unique ID of the Conversation for this participant.

sidtype: SID<MB>Not PII

A 34 character string that uniquely identifies this resource.

identitytype: stringPII 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 Conversation SDK to communicate. Limited to 256 characters.

attributestype: stringPII 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_bindingtype: objectPII MTL: 30 days

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

role_sidtype: SID<RL>Not PII

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

date_createdtype: string<DATE TIME>Not PII

The date on which this resource was created.

date_updatedtype: string<DATE TIME>Not PII

The date on which this resource was last updated.

urltype: string<URI>Not PII

An absolute API resource URL for this participant.

last_read_message_indextype: integerNot PII

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

last_read_timestamptype: stringNot PII

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

Create a Service-Scoped Participant resource

POST 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

Request headers

X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

URI parameters

ChatServiceSidtype: SID<IS>Not PII

Path Parameter

The SID of the Conversation Service the Participant resource is associated with.

ConversationSidtype: stringNot PII

Path Parameter

The unique ID of the Conversation for this participant.

Request body parameters

Identitytype: stringPII MTL: 30 days

MessagingBinding.Addresstype: stringNot 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).

MessagingBinding.ProxyAddresstype: stringNot 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).

DateCreatedtype: string<DATE TIME>Not PII

The date on which this resource was created.

DateUpdatedtype: string<DATE TIME>Not PII

The date on which this resource was last updated.

Attributestype: stringPII MTL: 30 days

MessagingBinding.ProjectedAddresstype: stringNot PII

The address of the Twilio phone number that is used in Group MMS.

RoleSidtype: SID<RL>Not PII

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

Create a ServiceConversationParticipant

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_12// Download the helper library from https://www.twilio.com/docs/node/install
_12// Find your Account SID and Auth Token at twilio.com/console
_12// and set the environment variables. See http://twil.io/secure
_12const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12const authToken = process.env.TWILIO_AUTH_TOKEN;
_12const client = require('twilio')(accountSid, authToken);
_12
_12client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12                       .conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12                       .participants
_12                       .create()
_12                       .then(participant => console.log(participant.sid));

Output


_21{
_21  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "identity": null,
_21  "attributes": {
_21    "role": "driver"
_21  },
_21  "messaging_binding": {
_21    "type": "sms",
_21    "address": "+15558675310",
_21    "proxy_address": "+15017122661"
_21  },
_21  "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "date_created": "2015-12-16T22:18:37Z",
_21  "date_updated": "2015-12-16T22:18:38Z",
_21  "url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "last_read_message_index": null,
_21  "last_read_timestamp": null
_21}

Fetch a Service-Scoped Participant resource

GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants/{Sid}

Parameters

URI parameters

ChatServiceSidtype: SID<IS>Not PII

Path Parameter

The SID of the Conversation Service the Participant resource is associated with.

ConversationSidtype: stringNot PII

Path Parameter

The unique ID of the Conversation for this participant.

Sidtype: stringNot PII

Path Parameter

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

Fetch a Service-Scoped Participant resource by SID

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_12// Download the helper library from https://www.twilio.com/docs/node/install
_12// Find your Account SID and Auth Token at twilio.com/console
_12// and set the environment variables. See http://twil.io/secure
_12const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12const authToken = process.env.TWILIO_AUTH_TOKEN;
_12const client = require('twilio')(accountSid, authToken);
_12
_12client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .participants('MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .fetch()
_12      .then(participant => console.log(participant.chatServiceSid));

Output


_21{
_21  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "identity": null,
_21  "attributes": {
_21    "role": "driver"
_21  },
_21  "messaging_binding": {
_21    "type": "sms",
_21    "address": "+15558675310",
_21    "proxy_address": "+15017122661"
_21  },
_21  "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "date_created": "2016-03-24T21:05:50Z",
_21  "date_updated": "2016-03-24T21:05:50Z",
_21  "url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "last_read_message_index": null,
_21  "last_read_timestamp": null
_21}

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

Fetch a Service-Scoped Participant resource by identity

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_12// Download the helper library from https://www.twilio.com/docs/node/install
_12// Find your Account SID and Auth Token at twilio.com/console
_12// and set the environment variables. See http://twil.io/secure
_12const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12const authToken = process.env.TWILIO_AUTH_TOKEN;
_12const client = require('twilio')(accountSid, authToken);
_12
_12client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .participants('alice')
_12      .fetch()
_12      .then(participant => console.log(participant.chatServiceSid));

Output


_21{
_21  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "identity": "alice",
_21  "attributes": {
_21    "role": "driver"
_21  },
_21  "messaging_binding": {
_21    "type": "sms",
_21    "address": "+15558675310",
_21    "proxy_address": "+15017122661"
_21  },
_21  "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "date_created": "2016-03-24T21:05:50Z",
_21  "date_updated": "2016-03-24T21:05:50Z",
_21  "url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "last_read_message_index": null,
_21  "last_read_timestamp": null
_21}

Read multiple Service-Scoped Participant resources

GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants

Parameters

URI parameters

ChatServiceSidtype: SID<IS>Not PII

Path Parameter

The SID of the Conversation Service the Participant resource is associated with.

ConversationSidtype: stringNot PII

Path Parameter

The unique ID of the Conversation for participants.

PageSizetype: integerNot PII

Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Pagetype: integerNot PII

Query Parameter

The page index. This value is simply for client state.

PageTokentype: stringNot PII

Query Parameter

The page token. This is provided by the API.

List multiple ServiceConversationParticipants

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_12// Download the helper library from https://www.twilio.com/docs/node/install
_12// Find your Account SID and Auth Token at twilio.com/console
_12// and set the environment variables. See http://twil.io/secure
_12const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12const authToken = process.env.TWILIO_AUTH_TOKEN;
_12const client = require('twilio')(accountSid, authToken);
_12
_12client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .participants
_12      .list({limit: 20})
_12      .then(participants => participants.forEach(p => console.log(p.sid)));

Output


_51{
_51  "meta": {
_51    "page": 0,
_51    "page_size": 50,
_51    "first_page_url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?PageSize=50&Page=0",
_51    "previous_page_url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?PageSize=50&Page=0",
_51    "url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?PageSize=50&Page=0",
_51    "next_page_url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?PageSize=50&Page=1",
_51    "key": "participants"
_51  },
_51  "participants": [
_51    {
_51      "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "identity": null,
_51      "attributes": {
_51        "role": "driver"
_51      },
_51      "messaging_binding": {
_51        "type": "sms",
_51        "address": "+15558675310",
_51        "proxy_address": "+15017122661"
_51      },
_51      "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "date_created": "2016-03-24T21:05:50Z",
_51      "date_updated": "2016-03-24T21:05:50Z",
_51      "url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "last_read_message_index": null,
_51      "last_read_timestamp": null
_51    },
_51    {
_51      "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "identity": "IDENTITY",
_51      "attributes": {
_51        "role": "driver"
_51      },
_51      "messaging_binding": null,
_51      "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "date_created": "2016-03-24T21:05:50Z",
_51      "date_updated": "2016-03-24T21:05:50Z",
_51      "url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51      "last_read_message_index": null,
_51      "last_read_timestamp": null
_51    }
_51  ]
_51}

Update a Service-Scoped Participant resource

POST https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants/{Sid}

Parameters

Request headers

X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

URI parameters

ChatServiceSidtype: SID<IS>Not PII

Path Parameter

The SID of the Conversation Service the Participant resource is associated with.

ConversationSidtype: stringNot PII

Path Parameter

The unique ID of the Conversation for this participant.

Sidtype: stringNot PII

Path Parameter

A 34 character string that uniquely identifies this resource.

Request body parameters

DateCreatedtype: string<DATE TIME>Not PII

The date on which this resource was created.

DateUpdatedtype: string<DATE TIME>Not PII

The date on which this resource was last updated.

Identitytype: stringPII MTL: 30 days

Attributestype: stringPII MTL: 30 days

RoleSidtype: SID<RL>Not PII

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

MessagingBinding.ProxyAddresstype: stringNot PII

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

MessagingBinding.ProjectedAddresstype: stringNot PII

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

LastReadMessageIndextype: integerNot PII

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

LastReadTimestamptype: stringNot PII

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

Update a ServiceConversationParticipant

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_12// Download the helper library from https://www.twilio.com/docs/node/install
_12// Find your Account SID and Auth Token at twilio.com/console
_12// and set the environment variables. See http://twil.io/secure
_12const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12const authToken = process.env.TWILIO_AUTH_TOKEN;
_12const client = require('twilio')(accountSid, authToken);
_12
_12client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .participants('MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12      .update({dateCreated: new Date(Date.UTC(2008, 0, 2, 0, 0, 0))})
_12      .then(participant => console.log(participant.chatServiceSid));

Output


_21{
_21  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "identity": null,
_21  "attributes": {
_21    "role": "driver"
_21  },
_21  "messaging_binding": {
_21    "type": "sms",
_21    "address": "+15558675310",
_21    "proxy_address": "+15017122661"
_21  },
_21  "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "date_created": "2015-12-16T22:18:37Z",
_21  "date_updated": "2015-12-16T22:18:38Z",
_21  "url": "https://conversations.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "last_read_message_index": null,
_21  "last_read_timestamp": null
_21}

Delete a Service-Scoped Conversation Participant resource

DELETE https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Conversations/{ConversationSid}/Participants/{Sid}

Deleting a participant removes them from the Conversation; they will receive no new messages after that point.

Parameters

Request headers

X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

URI parameters

ChatServiceSidtype: SID<IS>Not PII

Path Parameter

The SID of the Conversation Service the Participant resource is associated with.

ConversationSidtype: stringNot PII

Path Parameter

The unique ID of the Conversation for this participant.

Sidtype: stringNot PII

Path Parameter

A 34 character string that uniquely identifies this resource.

Delete a ServiceConversationParticipant

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_11// Download the helper library from https://www.twilio.com/docs/node/install
_11// Find your Account SID and Auth Token at twilio.com/console
_11// and set the environment variables. See http://twil.io/secure
_11const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11const authToken = process.env.TWILIO_AUTH_TOKEN;
_11const client = require('twilio')(accountSid, authToken);
_11
_11client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11                       .conversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11                       .participants('MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11                       .remove();