Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Conversations User Resource


In Conversations, Users are Participants with privileges such as the ability to edit and delete Messages.

Every Conversation Participant who connects with a Chat SDK (browser or mobile) is backed by a User. Participants over SMS or other non-chat channel, in contrast, do not have a corresponding User. Attached to the User is:

  • the Role assigned to the User , which determines their permissions in your application
  • a JSON blob of arbitrary Attributes , which you can use to store profile information for display in your application
  • Online/Offline status , determined by whether the User is presently connected through a frontend SDK
  • the Identity string , which uniquely identifies a user in each Conversation Service.

We recommend following the standard URI specification and avoid the following reserved characters ! * ' ( ) ; : @ & = + $ , / ? % # [ ] for values such as identity and friendly name.


API Base URL

api-base-url page anchor

All URLs in the reference documentation use the following base URL:


_10
https://conversations.twilio.com/v1

Using the shortened base URL

using-the-shortened-base-url page anchor

Using the REST API, you can interact with User 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.


_10
GET /v1/Users/

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:


_10
GET /v1/Services/<Service SID, ISXXX...>/Users/


Resource properties
sidtype: SID<US>Not PII

The unique string that we created to identify the User resource.


chat_service_sidtype: SID<IS>Not PII

The SID of the Conversation Service(link takes you to an external page) the User resource is associated with.


role_sidtype: SID<RL>Not PII

The SID of a service-level Role(link takes you to an external page) assigned to the user.


identitytype: stringPII MTL: 30 days

The application-defined string that uniquely identifies the resource's User within the Conversation Service(link takes you to an external page). This value is often a username or an email address, and is case-sensitive.


friendly_nametype: stringPII MTL: 30 days

The string that you assigned to describe the resource.


attributestype: stringPII MTL: 30 days

The JSON Object string that stores application-specific data. If attributes have not been set, {} is returned.


is_onlinetype: booleanNot PII

Whether the User is actively connected to this Conversations Service and online. This value is only returned by Fetch actions that return a single resource and null is always returned by a Read action. This value is null if the Service's reachability_enabled is false, if the User has never been online for this Conversations Service, even if the Service's reachability_enabled is true.


is_notifiabletype: booleanNot PII

Whether the User has a potentially valid Push Notification registration (APN or GCM) for this Conversations Service. If at least one registration exists, true; otherwise false. This value is only returned by Fetch actions that return a single resource and null is always returned by a Read action. This value is null if the Service's reachability_enabled is false, and if the User has never had a notification registration, even if the Service's reachability_enabled is true.


date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


urltype: string<URI>Not PII

An absolute API resource URL for this user.


linkstype: object<URI MAP>Not PII

Create a Conversations User

create-a-conversations-user page anchor
POST https://conversations.twilio.com/v1/Users

Parameters

create-parameters page anchor
Request headers
X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse

Request body parameters
Identitytype: stringPII MTL: 30 days
Required

The application-defined string that uniquely identifies the resource's User within the Conversation Service(link takes you to an external page). This value is often a username or an email address, and is case-sensitive.


FriendlyNametype: stringPII MTL: 30 days

The string that you assigned to describe the resource.


Attributestype: stringPII MTL: 30 days

The JSON Object string that stores application-specific data. If attributes have not been set, {} is returned.


RoleSidtype: SID<RL>Not PII

The SID of a service-level Role(link takes you to an external page) to assign to the user.

Users are usually autocreated with default roles the first time the appear. To control a User's assigned Role from the moment of creation, use this resource.

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
_10
.create({identity: 'RedgrenGrumbholdt'})
_10
.then(user => console.log(user.sid));

Output

_19
{
_19
"sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"identity": "RedgrenGrumbholdt",
_19
"friendly_name": "name",
_19
"attributes": {
_19
"duty": "tech"
_19
},
_19
"is_online": true,
_19
"is_notifiable": null,
_19
"date_created": "2019-12-16T22:18:37Z",
_19
"date_updated": "2019-12-16T22:18:38Z",
_19
"url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"links": {
_19
"user_conversations": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations"
_19
}
_19
}


Fetch a specific User Resource

fetch-a-specific-user-resource page anchor
GET https://conversations.twilio.com/v1/Users/{Sid}

URI parameters
Sidtype: stringNot PII
Path Parameter

The SID of the User resource to fetch. This value can be either the sid or the identity of the User resource to fetch.

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('USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(user => console.log(user.friendlyName));

Output

_19
{
_19
"sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"identity": "admin",
_19
"friendly_name": "name",
_19
"attributes": {
_19
"duty": "tech"
_19
},
_19
"is_online": true,
_19
"is_notifiable": null,
_19
"date_created": "2019-12-16T22:18:37Z",
_19
"date_updated": "2019-12-16T22:18:38Z",
_19
"url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"links": {
_19
"user_conversations": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations"
_19
}
_19
}


Read multiple ConversationUser resources

read-multiple-conversationuser-resources page anchor
GET https://conversations.twilio.com/v1/Users

URI parameters
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.

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
_10
.list({limit: 20})
_10
.then(users => users.forEach(u => console.log(u.sid)));

Output

_51
{
_51
"meta": {
_51
"page": 0,
_51
"page_size": 50,
_51
"first_page_url": "https://conversations.twilio.com/v1/Users?PageSize=50&Page=0",
_51
"previous_page_url": "https://conversations.twilio.com/v1/Users?PageSize=50&Page=0",
_51
"url": "https://conversations.twilio.com/v1/Users?PageSize=50&Page=0",
_51
"next_page_url": "https://conversations.twilio.com/v1/Users?PageSize=50&Page=1",
_51
"key": "users"
_51
},
_51
"users": [
_51
{
_51
"sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"identity": "admin",
_51
"friendly_name": "name",
_51
"attributes": {
_51
"duty": "tech"
_51
},
_51
"is_online": true,
_51
"is_notifiable": null,
_51
"date_created": "2019-12-16T22:18:37Z",
_51
"date_updated": "2019-12-16T22:18:38Z",
_51
"url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"links": {
_51
"user_conversations": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations"
_51
}
_51
},
_51
{
_51
"sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"identity": "agent0034",
_51
"friendly_name": "John from customs",
_51
"attributes": {
_51
"duty": "agent"
_51
},
_51
"is_online": false,
_51
"is_notifiable": null,
_51
"date_created": "2020-03-24T20:38:21Z",
_51
"date_updated": "2020-03-24T20:38:21Z",
_51
"url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_51
"links": {
_51
"user_conversations": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations"
_51
}
_51
}
_51
]
_51
}


Update a ConversationUser resource

update-a-conversationuser-resource page anchor
POST https://conversations.twilio.com/v1/Users/{Sid}

Request headers
X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse

URI parameters
Sidtype: stringNot PII
Path Parameter

The SID of the User resource to update. This value can be either the sid or the identity of the User resource to update.


Request body parameters
FriendlyNametype: stringPII MTL: 30 days

The string that you assigned to describe the resource.


Attributestype: stringPII MTL: 30 days

The JSON Object string that stores application-specific data. If attributes have not been set, {} is returned.


RoleSidtype: SID<RL>Not PII

The SID of a service-level Role(link takes you to an external page) to assign to the user.

Example for updating the friendly_name and role_sid for a user

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.conversations.v1.users('USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13
.update({
_13
friendlyName: 'new name',
_13
roleSid: 'RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
_13
})
_13
.then(user => console.log(user.friendlyName));

Output

_20
{
_20
"sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"identity": "admin",
_20
"friendly_name": "new name",
_20
"attributes": {
_20
"duty": "tech",
_20
"team": "internals"
_20
},
_20
"is_online": true,
_20
"is_notifiable": null,
_20
"date_created": "2019-12-16T22:18:37Z",
_20
"date_updated": "2019-12-16T22:18:38Z",
_20
"url": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"links": {
_20
"user_conversations": "https://conversations.twilio.com/v1/Users/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conversations"
_20
}
_20
}


DELETE https://conversations.twilio.com/v1/Users/{Sid}

Request headers
X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse

URI parameters
Sidtype: stringNot PII
Path Parameter

The SID of the User resource to delete. This value can be either the sid or the identity of the User resource to delete.

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('USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();


Rate this page: