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.

Resource properties
account_sidtype: SID<AC>Not PII

chat_service_sidtype: SID<IS>Not PII

The unique ID of the Conversation Service(link takes you to an external page) this conversation belongs to.


conversation_sidtype: SID<CH>Not PII

The unique ID of the Conversation(link takes you to an external page) for this User Conversation.


unread_messages_counttype: integerNot PII

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


last_read_message_indextype: integerNot 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(link takes you to an external page) the user conversation belongs to.


user_sidtype: SID<US>Not PII

The unique string that identifies the User resource(link takes you to an external page).


friendly_nametype: stringPII 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: objectNot PII

Timer date values representing state update for this conversation.


attributestype: stringPII 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: stringNot 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: stringPII 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(link takes you to an external page) and conversation(link takes you to an external page) 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.

Parameters

fetch-parameters page anchor
URI parameters
UserSidtype: stringNot PII
Path Parameter

The unique SID identifier of the User resource(link takes you to an external page). This value can be either the sid or the identity of the User resource.


ConversationSidtype: stringNot PII
Path Parameter

The unique SID identifier of the Conversation. This value can be either the sid or the unique_name of the Conversation resource(link takes you to an external page).

Fetch a specific conversation

fetch-a-specific-conversation-1 page anchor
Node.js
Python
C#
Java
Go
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
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.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

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.

URI parameters
UserSidtype: stringNot PII
Path Parameter

The unique SID identifier of the User resource(link takes you to an external page). This value can be either the sid or the identity of the User resource.


PageSizetype: integerNot PII
Query Parameter

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


Pagetype: integerNot PII
Query Parameter

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


PageTokentype: stringNot PII
Query Parameter

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

_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
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.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

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

URI parameters
UserSidtype: stringNot PII
Path Parameter

The unique SID identifier of the User resource(link takes you to an external page). This value can be either the sid or the identity of the User resource.


ConversationSidtype: stringNot PII
Path Parameter

The unique SID identifier of the Conversation. This value can be either the sid or the unique_name of the Conversation resource(link takes you to an external page).


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: integerNot PII

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

_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
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.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

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.

URI parameters
UserSidtype: stringNot PII
Path Parameter

The unique SID identifier of the User resource(link takes you to an external page). This value can be either the sid or the identity of the User resource.


ConversationSidtype: stringNot PII
Path Parameter

The unique SID identifier of the Conversation. This value can be either the sid or the unique_name of the Conversation resource(link takes you to an external page).


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: integerNot PII

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

_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
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.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

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

URI parameters
UserSidtype: stringNot PII
Path Parameter

The unique SID identifier of the User resource(link takes you to an external page). This value can be either the sid or the identity of the User resource.


ConversationSidtype: stringNot PII
Path Parameter

The unique SID identifier of the Conversation. This value can be either the sid or the unique_name of the Conversation resource(link takes you to an external page).

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

_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
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.conversations.v1.users('USXXXXXXXXXXXXX')
_10
.userConversations('CHXXXXXXXXXXXXX')
_10
.remove();


Rate this page: