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.
All URLs in the reference documentation use the following base URL:
_10https://conversations.twilio.com/v1
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.
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:
_10GET /v1/Services/<Service SID, ISXXX...>/Users/
Property nameTypePIIDescription
The unique string that we created to identify the User resource.
Pattern: ^US[0-9a-fA-F]{32}$Min length: 34Max length: 34
The SID of the Account that created the User resource.
Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
The SID of the Conversation Service the User resource is associated with.
Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
The SID of a service-level Role assigned to the user.
Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34
The application-defined string that uniquely identifies the resource's User within the Conversation Service. This value is often a username or an email address, and is case-sensitive.
The string that you assigned to describe the resource.
The JSON Object string that stores application-specific data. If attributes have not been set, {} is returned.
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.
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_createdstring<date-time>
date_updatedstring<date-time>
An absolute API resource URL for this user.
POST https://conversations.twilio.com/v1/Users
Property nameTypeRequiredPIIDescription
The application-defined string that uniquely identifies the resource's User within the Conversation Service. This value is often a username or an email address, and is case-sensitive.
FriendlyNamestringOptional The string that you assigned to describe the resource.
The JSON Object string that stores application-specific data. If attributes have not been set, {} is returned.
The SID of a service-level Role to assign to the user.
Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34
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.
_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// 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);
_18async function createUser() {
_18 const user = await client.conversations.v1.users.create({
_18 identity: "RedgrenGrumbholdt",
_18 console.log(user.sid);
_17 "sid": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "identity": "RedgrenGrumbholdt",
_17 "friendly_name": "name",
_17 "attributes": "{ \"duty\": \"tech\" }",
_17 "is_notifiable": null,
_17 "date_created": "2019-12-16T22:18:37Z",
_17 "date_updated": "2019-12-16T22:18:38Z",
_17 "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
GET https://conversations.twilio.com/v1/Users/{Sid}
Property nameTypeRequiredPIIDescription
The SID of the User resource to fetch. This value can be either the sid or the identity of the User resource to fetch.
_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16async function fetchUser() {
_16 const user = await client.conversations.v1.users("Sid").fetch();
_16 console.log(user.sid);
_17 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "friendly_name": "name",
_17 "attributes": "{ \"duty\": \"tech\" }",
_17 "is_notifiable": null,
_17 "date_created": "2019-12-16T22:18:37Z",
_17 "date_updated": "2019-12-16T22:18:38Z",
_17 "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
GET https://conversations.twilio.com/v1/Users
Property nameTypeRequiredPIIDescription
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Minimum: 1Maximum: 1000
The page index. This value is simply for client state.
Minimum: 0
The page token. This is provided by the API.
_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16async function listUser() {
_16 const users = await client.conversations.v1.users.list({ limit: 20 });
_16 users.forEach((u) => console.log(u.sid));
_47 "first_page_url": "https://conversations.twilio.com/v1/Users?PageSize=50&Page=0",
_47 "previous_page_url": null,
_47 "url": "https://conversations.twilio.com/v1/Users?PageSize=50&Page=0",
_47 "next_page_url": null,
_47 "sid": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "friendly_name": "name",
_47 "attributes": "{ \"duty\": \"tech\" }",
_47 "is_notifiable": null,
_47 "date_created": "2019-12-16T22:18:37Z",
_47 "date_updated": "2019-12-16T22:18:38Z",
_47 "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
_47 "sid": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "identity": "agent0034",
_47 "friendly_name": "John from customs",
_47 "attributes": "{ \"duty\": \"agent\" }",
_47 "is_notifiable": null,
_47 "date_created": "2020-03-24T20:38:21Z",
_47 "date_updated": "2020-03-24T20:38:21Z",
_47 "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_47 "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
POST https://conversations.twilio.com/v1/Users/{Sid}
Property nameTypeRequiredPIIDescription
The SID of the User resource to update. This value can be either the sid or the identity of the User resource to update.
Property nameTypeRequiredPIIDescription
FriendlyNamestringOptional The string that you assigned to describe the resource.
The JSON Object string that stores application-specific data. If attributes have not been set, {} is returned.
The SID of a service-level Role to assign to the user.
Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34
Example for updating the friendly_name and role_sid for a user
_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// 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);
_19async function updateUser() {
_19 const user = await client.conversations.v1.users("Sid").update({
_19 friendlyName: "new name",
_19 roleSid: "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19 console.log(user.sid);
_17 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "friendly_name": "new name",
_17 "attributes": "{ \"duty\": \"tech\", \"team\": \"internals\" }",
_17 "is_notifiable": null,
_17 "date_created": "2019-12-16T22:18:37Z",
_17 "date_updated": "2019-12-16T22:18:38Z",
_17 "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_17 "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
DELETE https://conversations.twilio.com/v1/Users/{Sid}
Property nameTypeRequiredPIIDescription
The SID of the User resource to delete. This value can be either the sid or the identity of the User resource to delete.
_14// Download the helper library from https://www.twilio.com/docs/node/install
_14const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_14// Find your Account SID and Auth Token at twilio.com/console
_14// and set the environment variables. See http://twil.io/secure
_14const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14const authToken = process.env.TWILIO_AUTH_TOKEN;
_14const client = twilio(accountSid, authToken);
_14async function deleteUser() {
_14 await client.conversations.v1.users("Sid").remove();