Skip to content Skip to navigation Skip to topbar

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

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

1https://conversations.twilio.com/v1
2

Using the shortened base URL

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.

1GET /v1/Users/
2

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:

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

User Properties

Property nameTypeRequiredDescriptionChild properties

sidSID<US>

Optional

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

Pattern: ^US[0-9a-fA-F]{32}$Min length: 34Max length: 34

account_sidSID<AC>

Optional

The SID of the Account that created the User resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

chat_service_sidSID<IS>

Optional

The SID of the Conversation Service the User resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

role_sidSID<RL>

Optional

The SID of a service-level Role assigned to the user.

Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34

identitystring

Optional

PII MTL: 30 days

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.

friendly_namestring

Optional

PII MTL: 30 days

The string that you assigned to describe the resource.

attributesstring

Optional

PII MTL: 30 days

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

is_onlineboolean

Optional

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_notifiableboolean

Optional

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>

Optional

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updatedstring<date-time>

Optional

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

urlstring<uri>

Optional

An absolute API resource URL for this user.

linksobject<uri-map>

Optional

Create a Conversations User

POST https://conversations.twilio.com/v1/Users

Headers

Property nameTypeRequiredPIIDescription

X-Twilio-Webhook-Enabledenum<string>

Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Identitystringrequired

PII MTL: 30 days

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.

FriendlyNamestring

Optional

PII MTL: 30 days

The string that you assigned to describe the resource.

Attributesstring

Optional

PII MTL: 30 days

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

RoleSidSID<RL>

Optional

The SID of a service-level Role to assign to the user.

Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34

Create a User

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createUser() {
11  const user = await client.conversations.v1.users.create({
12    identity: "RedgrenGrumbholdt",
13  });
14
15  console.log(user.sid);
16}
17
18createUser();

Output

1{
2  "sid": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "identity": "RedgrenGrumbholdt",
7  "friendly_name": "name",
8  "attributes": "{ \"duty\": \"tech\" }",
9  "is_online": true,
10  "is_notifiable": null,
11  "date_created": "2019-12-16T22:18:37Z",
12  "date_updated": "2019-12-16T22:18:38Z",
13  "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "links": {
15    "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
16  }
17}

Fetch a specific User Resource

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

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

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

Fetch an User

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchUser() {
11  const user = await client.conversations.v1.users("Sid").fetch();
12
13  console.log(user.sid);
14}
15
16fetchUser();

Output

1{
2  "sid": "Sid",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "identity": "admin",
7  "friendly_name": "name",
8  "attributes": "{ \"duty\": \"tech\" }",
9  "is_online": true,
10  "is_notifiable": null,
11  "date_created": "2019-12-16T22:18:37Z",
12  "date_updated": "2019-12-16T22:18:38Z",
13  "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "links": {
15    "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
16  }
17}

Read multiple ConversationUser resources

GET https://conversations.twilio.com/v1/Users

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeinteger

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

The page token. This is provided by the API.

List multiple Users

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listUser() {
11  const users = await client.conversations.v1.users.list({ limit: 20 });
12
13  users.forEach((u) => console.log(u.sid));
14}
15
16listUser();

Output

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://conversations.twilio.com/v1/Users?PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://conversations.twilio.com/v1/Users?PageSize=50&Page=0",
8    "next_page_url": null,
9    "key": "users"
10  },
11  "users": [
12    {
13      "sid": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17      "identity": "admin",
18      "friendly_name": "name",
19      "attributes": "{ \"duty\": \"tech\" }",
20      "is_online": true,
21      "is_notifiable": null,
22      "date_created": "2019-12-16T22:18:37Z",
23      "date_updated": "2019-12-16T22:18:38Z",
24      "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25      "links": {
26        "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
27      }
28    },
29    {
30      "sid": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
31      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
32      "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
33      "role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
34      "identity": "agent0034",
35      "friendly_name": "John from customs",
36      "attributes": "{ \"duty\": \"agent\" }",
37      "is_online": false,
38      "is_notifiable": null,
39      "date_created": "2020-03-24T20:38:21Z",
40      "date_updated": "2020-03-24T20:38:21Z",
41      "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
42      "links": {
43        "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
44      }
45    }
46  ]
47}

Update a ConversationUser resource

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

Headers

Property nameTypeRequiredPIIDescription

X-Twilio-Webhook-Enabledenum<string>

Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

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

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

FriendlyNamestring

Optional

PII MTL: 30 days

The string that you assigned to describe the resource.

Attributesstring

Optional

PII MTL: 30 days

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

RoleSidSID<RL>

Optional

The SID of a service-level Role to assign to the user.

Pattern: ^RL[0-9a-fA-F]{32}$Min length: 34Max length: 34

Update a User

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateUser() {
11  const user = await client.conversations.v1.users("Sid").update({
12    friendlyName: "new name",
13    roleSid: "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14  });
15
16  console.log(user.sid);
17}
18
19updateUser();

Output

1{
2  "sid": "Sid",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "chat_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6  "identity": "admin",
7  "friendly_name": "new name",
8  "attributes": "{ \"duty\": \"tech\", \"team\": \"internals\" }",
9  "is_online": true,
10  "is_notifiable": null,
11  "date_created": "2019-12-16T22:18:37Z",
12  "date_updated": "2019-12-16T22:18:38Z",
13  "url": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "links": {
15    "user_conversations": "https://conversations.twilio.com/v1/Users/USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conversations"
16  }
17}

Delete an User resource

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

Headers

Property nameTypeRequiredPIIDescription

X-Twilio-Webhook-Enabledenum<string>

Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:

truefalse

Path parameters

Property nameTypeRequiredPIIDescription

Sidstringrequired

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

Delete an User

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteUser() {
11  await client.conversations.v1.users("Sid").remove();
12}
13
14deleteUser();