Skip to content Skip to navigation Skip to topbar

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

1GET /v1/Conversations/CHxx/Participants
2

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

Participant Properties

Property nameTypeRequiredDescriptionChild properties

accountSidSID<AC>

Optional

The unique ID of the Account responsible for this participant.

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

conversationSidSID<CH>

Optional

The unique ID of the Conversation for this participant.

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

sidSID<MB>

Optional

A 34 character string that uniquely identifies this resource.

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

identitystring

Optional

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.

attributesstring

Optional

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.

messagingBindingobject

Optional

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.

roleSidSID<RL>

Optional

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

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

dateCreatedstring<date-time>

Optional

The date that this resource was created.

dateUpdatedstring<date-time>

Optional

The date that this resource was last updated.

urlstring<uri>

Optional

An absolute API resource URL for this participant.

lastReadMessageIndexinteger

Optional

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

lastReadTimestampstring

Optional

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:

Their phone number as the messagingbinding.address
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.

Headers

Property nameTypeRequiredPIIDescription

xTwilioWebhookEnabledenum<string>

Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

The unique ID of the Conversation for this participant.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

identitystring

Optional

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.

messagingBindingAddressstring

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 proxy_address) is only null when the participant is interacting from an SDK endpoint (see the 'identity' field).

messagingBindingProxyAddressstring

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 'identity' field).

dateCreatedstring<date-time>

Optional

The date that this resource was created.

dateUpdatedstring<date-time>

Optional

The date that this resource was last updated.

attributesstring

Optional

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.

messagingBindingProjectedAddressstring

Optional

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

roleSidSID<RL>

Optional

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 Conversation Participant (SMS)

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createConversationParticipant() {
11  const participant = await client.conversations.v1
12    .conversations("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .participants.create({
14      "messagingBinding.address": "+15558675310",
15      "messagingBinding.proxyAddress": "<Your Twilio Number>",
16    });
17
18  console.log(participant.sid);
19}
20
21createConversationParticipant();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4  "sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "identity": null,
6  "attributes": "{ \"role\": \"driver\" }",
7  "messaging_binding": {
8    "type": "sms",
9    "address": "+15558675310",
10    "proxy_address": "+15017122661"
11  },
12  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "date_created": "2015-12-16T22:18:37Z",
14  "date_updated": "2015-12-16T22:18:38Z",
15  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16  "last_read_message_index": null,
17  "last_read_timestamp": null
18}

Create Conversation Participant (Chat)

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createConversationParticipant() {
11  const participant = await client.conversations.v1
12    .conversations("ConversationSid")
13    .participants.create({ identity: "<Chat User Identity>" });
14
15  console.log(participant.sid);
16}
17
18createConversationParticipant();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "conversation_sid": "ConversationSid",
4  "sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "identity": "<Chat User Identity>",
6  "attributes": "{ \"role\": \"driver\" }",
7  "messaging_binding": null,
8  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9  "date_created": "2015-12-16T22:18:37Z",
10  "date_updated": "2015-12-16T22:18:38Z",
11  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12  "last_read_message_index": null,
13  "last_read_timestamp": null
14}

Fetch a ConversationParticipant resource

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

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

The unique ID of the Conversation for this participant.

sidstring

required

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

Fetch Conversation Participant by SID

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchConversationParticipant() {
11  const participant = await client.conversations.v1
12    .conversations("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .participants("MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .fetch();
15
16  console.log(participant.accountSid);
17}
18
19fetchConversationParticipant();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4  "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "identity": null,
6  "attributes": "{ \"role\": \"driver\" }",
7  "messaging_binding": {
8    "type": "sms",
9    "address": "+15558675310",
10    "proxy_address": "+15017122661"
11  },
12  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "date_created": "2016-03-24T21:05:50Z",
14  "date_updated": "2016-03-24T21:05:50Z",
15  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16  "last_read_message_index": null,
17  "last_read_timestamp": null
18}

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

Fetch Conversation Participant by identity

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchConversationParticipant() {
11  const participant = await client.conversations.v1
12    .conversations("ConversationSid")
13    .participants("alice")
14    .fetch();
15
16  console.log(participant.accountSid);
17}
18
19fetchConversationParticipant();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "conversation_sid": "ConversationSid",
4  "sid": "alice",
5  "identity": "alice",
6  "attributes": "{ \"role\": \"driver\" }",
7  "messaging_binding": {
8    "type": "sms",
9    "address": "+15558675310",
10    "proxy_address": "+15017122661"
11  },
12  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "date_created": "2016-03-24T21:05:50Z",
14  "date_updated": "2016-03-24T21:05:50Z",
15  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16  "last_read_message_index": null,
17  "last_read_timestamp": null
18}

Read multiple ConversationParticipant resources

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

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

The unique ID of the Conversation for participants.

Query parameters

Property nameTypeRequiredPIIDescription

pageSizeinteger<int64>

Optional

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

Minimum: 1Maximum: 1000

pageinteger

Optional

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

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

List Conversation Participant(s)

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listConversationParticipant() {
11  const participants = await client.conversations.v1
12    .conversations("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .participants.list({ limit: 20 });
14
15  participants.forEach((p) => console.log(p.accountSid));
16}
17
18listConversationParticipant();

Response

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",
8    "next_page_url": null,
9    "key": "participants"
10  },
11  "participants": [
12    {
13      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "identity": null,
17      "attributes": "{ \"role\": \"driver\" }",
18      "messaging_binding": {
19        "type": "sms",
20        "address": "+15558675310",
21        "proxy_address": "+15017122661"
22      },
23      "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24      "date_created": "2016-03-24T21:05:50Z",
25      "date_updated": "2016-03-24T21:05:50Z",
26      "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27      "last_read_message_index": null,
28      "last_read_timestamp": null
29    },
30    {
31      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32      "conversation_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
33      "sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
34      "identity": "IDENTITY",
35      "attributes": "{ \"role\": \"driver\" }",
36      "messaging_binding": null,
37      "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
38      "date_created": "2016-03-24T21:05:50Z",
39      "date_updated": "2016-03-24T21:05:50Z",
40      "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
41      "last_read_message_index": null,
42      "last_read_timestamp": null
43    }
44  ]
45}

Update a ConversationParticipant resource

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

Headers

Property nameTypeRequiredPIIDescription

xTwilioWebhookEnabledenum<string>

Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

The unique ID of the Conversation for this participant.

sidstring

required

A 34 character string that uniquely identifies this resource.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

dateCreatedstring<date-time>

Optional

The date that this resource was created.

dateUpdatedstring<date-time>

Optional

The date that this resource was last updated.

attributesstring

Optional

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.

roleSidSID<RL>

Optional

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

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

messagingBindingProxyAddressstring

Optional

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

messagingBindingProjectedAddressstring

Optional

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

identitystring

Optional

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.

lastReadMessageIndexinteger

Optional

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

lastReadTimestampstring

Optional

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

Update Conversation Participant

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateConversationParticipant() {
11  const participant = await client.conversations.v1
12    .conversations("ConversationSid")
13    .participants("Sid")
14    .update({ dateUpdated: new Date("2019-05-15 13:37:35") });
15
16  console.log(participant.accountSid);
17}
18
19updateConversationParticipant();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "conversation_sid": "ConversationSid",
4  "sid": "Sid",
5  "identity": null,
6  "attributes": "{ \"role\": \"driver\" }",
7  "messaging_binding": {
8    "type": "sms",
9    "address": "+15558675310",
10    "proxy_address": "+15017122661"
11  },
12  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "date_created": "2015-12-16T22:18:37Z",
14  "date_updated": "2019-05-15T13:37:35Z",
15  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16  "last_read_message_index": null,
17  "last_read_timestamp": null
18}

Update attributes for a Conversation Participant

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateConversationParticipant() {
11  const participant = await client.conversations.v1
12    .conversations("ConversationSid")
13    .participants("Sid")
14    .update({ attributes: JSON.stringify({ role: "driver" }) });
15
16  console.log(participant.accountSid);
17}
18
19updateConversationParticipant();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "conversation_sid": "ConversationSid",
4  "sid": "Sid",
5  "identity": null,
6  "attributes": "{\"role\": \"driver\"}",
7  "messaging_binding": {
8    "type": "sms",
9    "address": "+15558675310",
10    "proxy_address": "+15017122661"
11  },
12  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "date_created": "2015-12-16T22:18:37Z",
14  "date_updated": "2015-12-16T22:18:38Z",
15  "url": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16  "last_read_message_index": null,
17  "last_read_timestamp": null
18}

Delete a ConversationParticipant resource

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

Headers

Property nameTypeRequiredPIIDescription

xTwilioWebhookEnabledenum<string>

Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Path parameters

Property nameTypeRequiredPIIDescription

conversationSidstring

required

The unique ID of the Conversation for this participant.

sidstring

required

A 34 character string that uniquely identifies this resource.

Delete Conversation Participant

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteConversationParticipant() {
11  await client.conversations.v1
12    .conversations("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .participants("MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .remove();
15}
16
17deleteConversationParticipant();