Skip to contentSkip to navigationSkip to topbar
Rate this page:
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

userconversation-properties page anchor

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>

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>

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

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


last_read_message_indexinteger

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


participant_sidSID<MB>

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>

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>

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

Possible values:
inactiveactiveclosed

timersobject

Timer date values representing state update for this conversation.


attributesstring

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>

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


date_updatedstring<date-time>

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


created_bystring

Identity of the creator of this Conversation.


notification_levelenum<string>

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

Possible values:
defaultmuted

unique_namestring

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>

linksobject<uri-map>

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


Fetch a specific conversation

fetch-a-specific-conversation page anchor
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

path-parameters page anchor
Property nameTypeRequiredPIIDescription
UserSidstringrequired

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


ConversationSidstringrequired

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

fetch-a-specific-conversation-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const 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
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async 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
_19
fetchUserConversation();

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

list-all-of-a-users-conversations page anchor
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.

Property nameTypeRequiredPIIDescription
UserSidstringrequired

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

Property nameTypeRequiredPIIDescription
PageSizeintegerOptional

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

Minimum: 1Maximum: 1000

PageintegerOptional

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

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

List All of a User's Conversations

list-all-of-a-users-conversations-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
const 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
_18
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18
const authToken = process.env.TWILIO_AUTH_TOKEN;
_18
const client = twilio(accountSid, authToken);
_18
_18
async 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
_18
listUserConversation();

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

update-a-specific-conversation page anchor
POST https://conversations.twilio.com/v1/Users/{UserSid}/Conversations/{ConversationSid}

Property nameTypeRequiredPIIDescription
UserSidstringrequired

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


ConversationSidstringrequired

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

Property nameTypeRequiredPIIDescription
NotificationLevelenum<string>Optional

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

Possible values:
defaultmuted

LastReadTimestampstring<date-time>Optional

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


LastReadMessageIndexintegerOptional

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

Update a specific conversation

update-a-specific-conversation-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const 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
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function updateUserConversation() {
_19
const userConversation = await client.conversations.v1
_19
.users("USXXXXXXXXXXXXX")
_19
.userConversations("CHXXXXXXXXXXXXX")
_19
.update({ notificationLevel: "muted" });
_19
_19
console.log(userConversation.accountSid);
_19
}
_19
_19
updateUserConversation();

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": "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
}


Set the NotificationLevel for a conversation

set-the-notificationlevel-for-a-conversation page anchor
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.

Property nameTypeRequiredPIIDescription
UserSidstringrequired

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


ConversationSidstringrequired

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

Property nameTypeRequiredPIIDescription
NotificationLevelenum<string>Optional

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

Possible values:
defaultmuted

LastReadTimestampstring<date-time>Optional

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


LastReadMessageIndexintegerOptional

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

Mute Notifications for a Conversation

mute-notifications-for-a-conversation page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const 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
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async 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
_19
updateUserConversation();

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

remove-a-user-from-one-of-their-conversations page anchor
DELETE https://conversations.twilio.com/v1/Users/{UserSid}/Conversations/{ConversationSid}

Property nameTypeRequiredPIIDescription
UserSidstringrequired

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


ConversationSidstringrequired

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

remove-a-user-from-one-of-their-conversations-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_17
// Download the helper library from https://www.twilio.com/docs/node/install
_17
const 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
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const authToken = process.env.TWILIO_AUTH_TOKEN;
_17
const client = twilio(accountSid, authToken);
_17
_17
async function deleteUserConversation() {
_17
await client.conversations.v1
_17
.users("USXXXXXXXXXXXXX")
_17
.userConversations("CHXXXXXXXXXXXXX")
_17
.remove();
_17
}
_17
_17
deleteUserConversation();


Rate this page: