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

Property nameTypePIIDescription

account_sidSID<AC>

Not PII

The unique ID of the Account responsible for this participant.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

chat_service_sidSID<IS>

Not PII

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

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

conversation_sidSID<CH>

Not PII

The unique ID of the Conversation for this participant.

Pattern: ^CH[0-9a-fA-F]{32}$Min length: 34Max length: 34

sidSID<MB>

Not PII

A 34 character string that uniquely identifies this resource.

Pattern: ^MB[0-9a-fA-F]{32}$Min length: 34Max length: 34

identitystring

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

attributesstring

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_bindingobject

PII 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_sidSID<RL>

Not PII

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

Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34

date_createdstring<date-time>

Not PII

The date on which this resource was created.

date_updatedstring<date-time>

Not PII

The date on which this resource was last updated.

urlstring<uri>

Not PII

An absolute API resource URL for this participant.

last_read_message_indexinteger

Not PII

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

last_read_timestampstring

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

Headers

Property nameTypeRequiredPIIDescription

X-Twilio-Webhook-Enabledenum<string>Optional

Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Path parameters

Property nameTypeRequiredPIIDescription

ChatServiceSidSID<IS>required

Not PII

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

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ConversationSidstringrequired

Not PII

The unique ID of the Conversation for this participant.

Request body parameters

Property nameTypeRequiredPIIDescription

IdentitystringOptional

PII MTL: 30 days

MessagingBinding.AddressstringOptional

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

MessagingBinding.ProxyAddressstringOptional

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

DateCreatedstring<date-time>Optional

Not PII

The date on which this resource was created.

DateUpdatedstring<date-time>Optional

Not PII

The date on which this resource was last updated.

AttributesstringOptional

PII MTL: 30 days

MessagingBinding.ProjectedAddressstringOptional

Not PII

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

RoleSidSID<RL>Optional

Not PII

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

Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34

Create a ServiceConversationParticipant

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19
_19async function createServiceConversationParticipant() {
_19  const participant = await client.conversations.v1
_19    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19    .conversations("ConversationSid")
_19    .participants.create();
_19
_19  console.log(participant.accountSid);
_19}
_19
_19createServiceConversationParticipant();

Output


_19{
_19  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "conversation_sid": "ConversationSid",
_19  "sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "identity": "null",
_19  "attributes": "{ \"role\": \"driver\" }",
_19  "messaging_binding": {
_19    "type": "sms",
_19    "address": "+15558675310",
_19    "proxy_address": "+15017122661"
_19  },
_19  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "date_created": "2015-12-16T22:18:37Z",
_19  "date_updated": "2015-12-16T22:18:38Z",
_19  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "last_read_message_index": null,
_19  "last_read_timestamp": null
_19}

Fetch a Service-Scoped Participant resource

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

Path parameters

Property nameTypeRequiredPIIDescription

ChatServiceSidSID<IS>required

Not PII

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

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ConversationSidstringrequired

Not PII

The unique ID of the Conversation for this participant.

Sidstringrequired

Not PII

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


_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20
_20async function fetchServiceConversationParticipant() {
_20  const participant = await client.conversations.v1
_20    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_20    .conversations("ConversationSid")
_20    .participants("Sid")
_20    .fetch();
_20
_20  console.log(participant.accountSid);
_20}
_20
_20fetchServiceConversationParticipant();

Output


_19{
_19  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "conversation_sid": "ConversationSid",
_19  "sid": "Sid",
_19  "identity": null,
_19  "attributes": "{ \"role\": \"driver\" }",
_19  "messaging_binding": {
_19    "type": "sms",
_19    "address": "+15558675310",
_19    "proxy_address": "+15017122661"
_19  },
_19  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "date_created": "2016-03-24T21:05:50Z",
_19  "date_updated": "2016-03-24T21:05:50Z",
_19  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "last_read_message_index": null,
_19  "last_read_timestamp": null
_19}

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


_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20
_20async function fetchServiceConversationParticipant() {
_20  const participant = await client.conversations.v1
_20    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_20    .conversations("ConversationSid")
_20    .participants("alice")
_20    .fetch();
_20
_20  console.log(participant.accountSid);
_20}
_20
_20fetchServiceConversationParticipant();

Output


_19{
_19  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "conversation_sid": "ConversationSid",
_19  "sid": "alice",
_19  "identity": "alice",
_19  "attributes": "{ \"role\": \"driver\" }",
_19  "messaging_binding": {
_19    "type": "sms",
_19    "address": "+15558675310",
_19    "proxy_address": "+15017122661"
_19  },
_19  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "date_created": "2016-03-24T21:05:50Z",
_19  "date_updated": "2016-03-24T21:05:50Z",
_19  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "last_read_message_index": null,
_19  "last_read_timestamp": null
_19}

Read multiple Service-Scoped Participant resources

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

Path parameters

Property nameTypeRequiredPIIDescription

ChatServiceSidSID<IS>required

Not PII

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

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ConversationSidstringrequired

Not PII

The unique ID of the Conversation for participants.

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeintegerOptional

Not PII

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

Minimum: 1Maximum: 1000

PageintegerOptional

Not PII

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

Minimum: 0

PageTokenstringOptional

Not PII

The page token. This is provided by the API.

List multiple ServiceConversationParticipants

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19
_19async function listServiceConversationParticipant() {
_19  const participants = await client.conversations.v1
_19    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19    .conversations("ConversationSid")
_19    .participants.list({ limit: 20 });
_19
_19  participants.forEach((p) => console.log(p.accountSid));
_19}
_19
_19listServiceConversationParticipant();

Output


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

Update a Service-Scoped Participant resource

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

Headers

Property nameTypeRequiredPIIDescription

X-Twilio-Webhook-Enabledenum<string>Optional

Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Path parameters

Property nameTypeRequiredPIIDescription

ChatServiceSidSID<IS>required

Not PII

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

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ConversationSidstringrequired

Not PII

The unique ID of the Conversation for this participant.

Sidstringrequired

Not PII

A 34 character string that uniquely identifies this resource.

Request body parameters

Property nameTypeRequiredPIIDescription

DateCreatedstring<date-time>Optional

Not PII

The date on which this resource was created.

DateUpdatedstring<date-time>Optional

Not PII

The date on which this resource was last updated.

IdentitystringOptional

PII MTL: 30 days

AttributesstringOptional

PII MTL: 30 days

RoleSidSID<RL>Optional

Not PII

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

Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34

MessagingBinding.ProxyAddressstringOptional

Not PII

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

MessagingBinding.ProjectedAddressstringOptional

Not PII

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

LastReadMessageIndexintegerOptional

Not PII

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

LastReadTimestampstringOptional

Not PII

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

Update a ServiceConversationParticipant

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20
_20async function updateServiceConversationParticipant() {
_20  const participant = await client.conversations.v1
_20    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_20    .conversations("ConversationSid")
_20    .participants("Sid")
_20    .update({ dateCreated: new Date("2009-07-06 20:30:00") });
_20
_20  console.log(participant.accountSid);
_20}
_20
_20updateServiceConversationParticipant();

Output


_19{
_19  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "conversation_sid": "ConversationSid",
_19  "sid": "Sid",
_19  "identity": null,
_19  "attributes": "{ \"role\": \"driver\" }",
_19  "messaging_binding": {
_19    "type": "sms",
_19    "address": "+15558675310",
_19    "proxy_address": "+15017122661"
_19  },
_19  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "date_created": "2009-07-06T20:30:00Z",
_19  "date_updated": "2015-12-16T22:18:38Z",
_19  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_19  "last_read_message_index": null,
_19  "last_read_timestamp": null
_19}

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.

Headers

Property nameTypeRequiredPIIDescription

X-Twilio-Webhook-Enabledenum<string>Optional

Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Path parameters

Property nameTypeRequiredPIIDescription

ChatServiceSidSID<IS>required

Not PII

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

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ConversationSidstringrequired

Not PII

The unique ID of the Conversation for this participant.

Sidstringrequired

Not PII

A 34 character string that uniquely identifies this resource.

Delete a ServiceConversationParticipant

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function deleteServiceConversationParticipant() {
_18  await client.conversations.v1
_18    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18    .conversations("ConversationSid")
_18    .participants("Sid")
_18    .remove();
_18}
_18
_18deleteServiceConversationParticipant();