On this page

User Conversation Resource

The UserConversation resource lists the Conversations in which a particular User is an active Participant. Use this resource to:

list a user's conversations, present or historical,
mute a user's push notifications for specific channels, or
count a user's unread messages

(information)

Info

Please note that UnreadMessageCount returns a maximum value of 1000

UserConversation Properties

Each UserConversation resource contains these properties.

Property nameTypePIIDescription

account_sidSID<AC>

Not PII

The unique ID of the Account responsible for this conversation.

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

chat_service_sidSID<IS>

Not PII

The unique ID of the Conversation Service this conversation belongs to.

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 User Conversation.

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

unread_messages_countinteger

Not PII

The number of unread Messages in the Conversation for the Participant.

last_read_message_indexinteger

Not PII

The index of the last Message in the Conversation that the Participant has read.

participant_sidSID<MB>

Not PII

The unique ID of the participant the user conversation belongs to.

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

user_sidSID<US>

Not PII

The unique string that identifies the User resource.

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

friendly_namestring

PII MTL: 30 days

The human-readable name of this conversation, limited to 256 characters. Optional.

conversation_stateenum<string>

Not PII

The current state of this User Conversation. One of inactive, active or closed.

Possible values:

inactiveactiveclosed

timersobject

Not PII

Timer date values representing state update for this conversation.

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.

date_createdstring<date-time>

Not PII

The date that this conversation was created, given in ISO 8601 format.

date_updatedstring<date-time>

Not PII

The date that this conversation was last updated, given in ISO 8601 format.

created_bystring

Not PII

Identity of the creator of this Conversation.

notification_levelenum<string>

Not PII

The Notification Level of this User Conversation. One of default or muted.

Possible values:

defaultmuted

unique_namestring

PII MTL: 30 days

An application-defined string that uniquely identifies the Conversation resource. It can be used to address the resource in place of the resource's conversation_sid in the URL.

urlstring<uri>

Not PII

linksobject<uri-map>

Not PII

Contains absolute URLs to access the participant and conversation of this conversation.

Fetch a specific conversation

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

The {UserSid} value can be either the sid or the identity of the User resource and the {ConversationSid} value can be either the sid or the unique_name of the Conversation to fetch.

Path parameters

Property nameTypeRequiredPIIDescription

UserSidstringrequired

Not PII

The unique SID identifier of the User resource. This value can be either the sid or the identity of the User resource.

ConversationSidstringrequired

Not PII

The unique SID identifier of the Conversation. This value can be either the sid or the unique_name of the Conversation resource.

Fetch a specific conversation

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 fetchUserConversation() {
_19  const userConversation = await client.conversations.v1
_19    .users("USXXXXXXXXXXXXX")
_19    .userConversations("CHXXXXXXXXXXXXX")
_19    .fetch();
_19
_19  console.log(userConversation.accountSid);
_19}
_19
_19fetchUserConversation();

Output


_26{
_26  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "conversation_sid": "CHXXXXXXXXXXXXX",
_26  "unread_messages_count": 100,
_26  "last_read_message_index": 100,
_26  "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "user_sid": "USXXXXXXXXXXXXX",
_26  "friendly_name": "friendly_name",
_26  "conversation_state": "inactive",
_26  "timers": {
_26    "date_inactive": "2015-12-16T22:19:38Z",
_26    "date_closed": "2015-12-16T22:28:38Z"
_26  },
_26  "attributes": "{}",
_26  "date_created": "2015-07-30T20:00:00Z",
_26  "date_updated": "2015-07-30T20:00:00Z",
_26  "created_by": "created_by",
_26  "notification_level": "default",
_26  "unique_name": "unique_name",
_26  "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "links": {
_26    "participant": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26    "conversation": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_26  }
_26}

List All of a User's Conversations

GET https://conversations.twilio.com/v1/Users/{UserSid}/Conversations

The {UserSid} value can be either the sid or the identity of the User resource to read UserConversation resources from.

Path parameters

Property nameTypeRequiredPIIDescription

UserSidstringrequired

Not PII

The unique SID identifier of the User resource. This value can be either the sid or the identity of the User resource.

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 All of a User's Conversations

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 listUserConversation() {
_18  const userConversations = await client.conversations.v1
_18    .users("USXXXXXXXXXXXXX")
_18    .userConversations.list({ limit: 20 });
_18
_18  userConversations.forEach((u) => console.log(u.accountSid));
_18}
_18
_18listUserConversation();

Output


_12{
_12  "conversations": [],
_12  "meta": {
_12    "page": 0,
_12    "page_size": 50,
_12    "first_page_url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations?PageSize=50&Page=0",
_12    "previous_page_url": null,
_12    "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations?PageSize=50&Page=0",
_12    "next_page_url": null,
_12    "key": "conversations"
_12  }
_12}

Update a specific conversation

POST https://conversations.twilio.com/v1/Users/{UserSid}/Conversations/{ConversationSid}

Path parameters

Property nameTypeRequiredPIIDescription

UserSidstringrequired

Not PII

The unique SID identifier of the User resource. This value can be either the sid or the identity of the User resource.

ConversationSidstringrequired

Not PII

The unique SID identifier of the Conversation. This value can be either the sid or the unique_name of the Conversation resource.

Request body parameters

Property nameTypeRequiredPIIDescription

NotificationLevelenum<string>Optional

Not PII

The Notification Level of this User Conversation. One of default or muted.

Possible values:

defaultmuted

LastReadTimestampstring<date-time>Optional

Not PII

The date of the last message read in conversation by the user, given in ISO 8601 format.

LastReadMessageIndexintegerOptional

Not PII

The index of the last Message in the Conversation that the Participant has read.

Update a specific conversation

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 updateUserConversation() {
_19  const userConversation = await client.conversations.v1
_19    .users("USXXXXXXXXXXXXX")
_19    .userConversations("CHXXXXXXXXXXXXX")
_19    .update({ notificationLevel: "default" });
_19
_19  console.log(userConversation.accountSid);
_19}
_19
_19updateUserConversation();

Output


_26{
_26  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "conversation_sid": "CHXXXXXXXXXXXXX",
_26  "unread_messages_count": 100,
_26  "last_read_message_index": 100,
_26  "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "user_sid": "USXXXXXXXXXXXXX",
_26  "friendly_name": "friendly_name",
_26  "conversation_state": "inactive",
_26  "timers": {
_26    "date_inactive": "2015-12-16T22:19:38Z",
_26    "date_closed": "2015-12-16T22:28:38Z"
_26  },
_26  "attributes": "{}",
_26  "date_created": "2015-07-30T20:00:00Z",
_26  "date_updated": "2015-07-30T20:00:00Z",
_26  "created_by": "created_by",
_26  "notification_level": "default",
_26  "unique_name": "unique_name",
_26  "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "links": {
_26    "participant": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26    "conversation": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_26  }
_26}

Set the NotificationLevel for a conversation

POST https://conversations.twilio.com/v1/Users/{UserSid}/Conversations/{ConversationSid}

The NotificationLevel property expresses whether a user receives pushes for this conversation or not. This can be set separately for each user/conversation pair.

Path parameters

Property nameTypeRequiredPIIDescription

UserSidstringrequired

Not PII

The unique SID identifier of the User resource. This value can be either the sid or the identity of the User resource.

ConversationSidstringrequired

Not PII

The unique SID identifier of the Conversation. This value can be either the sid or the unique_name of the Conversation resource.

Request body parameters

Property nameTypeRequiredPIIDescription

NotificationLevelenum<string>Optional

Not PII

The Notification Level of this User Conversation. One of default or muted.

Possible values:

defaultmuted

LastReadTimestampstring<date-time>Optional

Not PII

The date of the last message read in conversation by the user, given in ISO 8601 format.

LastReadMessageIndexintegerOptional

Not PII

The index of the last Message in the Conversation that the Participant has read.

Mute Notifications for a Conversation

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 updateUserConversation() {
_19  const userConversation = await client.conversations.v1
_19    .users("UserSid")
_19    .userConversations("ConversationSid")
_19    .update({ notificationLevel: "muted" });
_19
_19  console.log(userConversation.notificationLevel);
_19}
_19
_19updateUserConversation();

Output


_26{
_26  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "conversation_sid": "ConversationSid",
_26  "unread_messages_count": 100,
_26  "last_read_message_index": 100,
_26  "participant_sid": "MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "user_sid": "UserSid",
_26  "friendly_name": "friendly_name",
_26  "conversation_state": "inactive",
_26  "timers": {
_26    "date_inactive": "2015-12-16T22:19:38Z",
_26    "date_closed": "2015-12-16T22:28:38Z"
_26  },
_26  "attributes": "{}",
_26  "date_created": "2015-07-30T20:00:00Z",
_26  "date_updated": "2015-07-30T20:00:00Z",
_26  "created_by": "created_by",
_26  "notification_level": "muted",
_26  "unique_name": "unique_name",
_26  "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26  "links": {
_26    "participant": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/MBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_26    "conversation": "https://conversations.twilio.com/v1/Conversations/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_26  }
_26}

Remove a User from one of their Conversations

DELETE https://conversations.twilio.com/v1/Users/{UserSid}/Conversations/{ConversationSid}

Path parameters

Property nameTypeRequiredPIIDescription

UserSidstringrequired

Not PII

The unique SID identifier of the User resource. This value can be either the sid or the identity of the User resource.

ConversationSidstringrequired

Not PII

The unique SID identifier of the Conversation. This value can be either the sid or the unique_name of the Conversation resource.

Remove a User from one of their Conversations

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_17// Download the helper library from https://www.twilio.com/docs/node/install
_17const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_17
_17// Find your Account SID and Auth Token at twilio.com/console
_17// and set the environment variables. See http://twil.io/secure
_17const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17const authToken = process.env.TWILIO_AUTH_TOKEN;
_17const client = twilio(accountSid, authToken);
_17
_17async function deleteUserConversation() {
_17  await client.conversations.v1
_17    .users("USXXXXXXXXXXXXX")
_17    .userConversations("CHXXXXXXXXXXXXX")
_17    .remove();
_17}
_17
_17deleteUserConversation();