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.

Resource properties

account_sidtype: SID<AC>

Not PII

The unique ID of the Account responsible for this conversation.

Pattern:

^AC[0-9a-fA-F]{32}$

Min length:

34

Max length:

34

chat_service_sidtype: SID<IS>

Not PII

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

Pattern:

^IS[0-9a-fA-F]{32}$

Min length:

34

Max length:

34

conversation_sidtype: SID<CH>

Not PII

The unique ID of the Conversation for this User Conversation.

Pattern:

^CH[0-9a-fA-F]{32}$

Min length:

34

Max length:

34

unread_messages_counttype: integer

Not PII

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

last_read_message_indextype: integer

Not PII

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

participant_sidtype: SID<MB>

Not PII

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

Pattern:

^MB[0-9a-fA-F]{32}$

Min length:

34

Max length:

34

user_sidtype: SID<US>

Not PII

The unique string that identifies the User resource.

Pattern:

^US[0-9a-fA-F]{32}$

Min length:

34

Max length:

34

friendly_nametype: string

PII MTL: 30 days

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

conversation_statetype: enum<string>

Not PII

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

Possible values:

inactiveactiveclosed

timerstype: object

Not PII

Timer date values representing state update for this conversation.

attributestype: string

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_createdtype: string<date-time>

Not PII

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

date_updatedtype: string<date-time>

Not PII

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

created_bytype: string

Not PII

Identity of the creator of this Conversation.

notification_leveltype: enum<string>

Not PII

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

Possible values:

defaultmuted

unique_nametype: string

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.

urltype: string<uri>

Not PII

linkstype: object<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.

Parameters

URI parameters

UserSidtype: string

Path ParameterNot PII

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

ConversationSidtype: string

Path ParameterNot 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


_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.users('USXXXXXXXXXXXXX')
_11      .userConversations('CHXXXXXXXXXXXXX')
_11      .fetch()
_11      .then(user_conversation => console.log(user_conversation.friendlyName));

Output


_26{
_26  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "unread_messages_count": 100,
_26  "last_read_message_index": 100,
_26  "participant_sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "user_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "links": {
_26    "participant": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26    "conversation": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_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.

Parameters

URI parameters

UserSidtype: string

Path ParameterNot PII

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

PageSizetype: integer

Query ParameterNot PII

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

Minimum:

1

Pagetype: integer

Query ParameterNot PII

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

Minimum:

0

PageTokentype: string

Query ParameterNot 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


_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.users('USXXXXXXXXXXXXX')
_11  .userConversations
_11  .list({limit: 20})
_11  .then(userConversations => userConversations.forEach(u => console.log(u.friendlyName)));

Output


_39{
_39  "conversations": [
_39    {
_39      "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39      "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39      "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39      "unread_messages_count": 100,
_39      "last_read_message_index": 100,
_39      "participant_sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39      "user_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39      "friendly_name": "friendly_name",
_39      "conversation_state": "inactive",
_39      "timers": {
_39        "date_inactive": "2015-12-16T22:19:38Z",
_39        "date_closed": "2015-12-16T22:28:38Z"
_39      },
_39      "attributes": {},
_39      "date_created": "2015-07-30T20:00:00Z",
_39      "date_updated": "2015-07-30T20:00:00Z",
_39      "created_by": "created_by",
_39      "notification_level": "default",
_39      "unique_name": "unique_name",
_39      "url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39      "links": {
_39        "participant": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39        "conversation": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_39      }
_39    }
_39  ],
_39  "meta": {
_39    "page": 0,
_39    "page_size": 50,
_39    "first_page_url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations?PageSize=50&Page=0",
_39    "previous_page_url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations?PageSize=50&Page=0",
_39    "url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations?PageSize=50&Page=0",
_39    "next_page_url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations?PageSize=50&Page=1",
_39    "key": "conversations"
_39  }
_39}

Update a specific conversation

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

Parameters

URI parameters

UserSidtype: string

Path ParameterNot PII

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

ConversationSidtype: string

Path ParameterNot 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

NotificationLeveltype: enum<string>

Not PII

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

Possible values:

defaultmuted

LastReadTimestamptype: string<date-time>

Not PII

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

LastReadMessageIndextype: integer

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


_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.users('USXXXXXXXXXXXXX')
_11      .userConversations('CHXXXXXXXXXXXXX')
_11      .update({notificationLevel: 'default'})
_11      .then(user_conversation => console.log(user_conversation.friendlyName));

Output


_26{
_26  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "unread_messages_count": 100,
_26  "last_read_message_index": 100,
_26  "participant_sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "user_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "links": {
_26    "participant": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26    "conversation": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_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.

Parameters

URI parameters

UserSidtype: string

Path ParameterNot PII

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

ConversationSidtype: string

Path ParameterNot 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

NotificationLeveltype: enum<string>

Not PII

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

Possible values:

defaultmuted

LastReadTimestamptype: string<date-time>

Not PII

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

LastReadMessageIndextype: integer

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


_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.users('USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11  .userConversations('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11  .update({notificationLevel: 'muted'})
_11  .then(user_conversation => console.log(user_conversation.notificationLevel));

Output


_26{
_26  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "unread_messages_count": 100,
_26  "last_read_message_index": 100,
_26  "participant_sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "user_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26  "links": {
_26    "participant": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26    "conversation": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_26  }
_26}

Remove a User from one of their Conversations

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

Parameters

URI parameters

UserSidtype: string

Path ParameterNot PII

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

ConversationSidtype: string

Path ParameterNot 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


_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10
_10client.conversations.v1.users('USXXXXXXXXXXXXX')
_10                       .userConversations('CHXXXXXXXXXXXXX')
_10                       .remove();