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:

https://conversations.twilio.com/v1

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.

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:

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

User properties

Resource Properties in REST API format
`sid`	sid<US> Not PII The unique string that we created to identify the User resource.
`account_sid`	sid<AC> Not PII The SID of the Account that created the User resource.
`chat_service_sid`	sid<IS> Not PII The SID of the Conversation Service the User resource is associated with.
`role_sid`	sid<RL> Not PII The SID of a service-level Role assigned to the user.
`identity`	string 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_name`	string PII MTL: 30 DAYS The string that you assigned to describe the resource.
`attributes`	string PII MTL: 30 DAYS The JSON Object string that stores application-specific data. If attributes have not been set, `{}` is returned.
`is_online`	boolean Not 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_notifiable`	boolean Not 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_created`	date_time<iso8601> Not PII The date and time in GMT when the resource was created specified in ISO 8601 format.
`date_updated`	date_time<iso8601> Not PII The date and time in GMT when the resource was last updated specified in ISO 8601 format.
`url`	url Not PII An absolute API resource URL for this user.
`links`	uri_map Not PII

Create a Conversations User

post

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

Parameters

Parameters in REST API format
`identity` Required	post string 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_name` Optional	post string PII MTL: 30 DAYS The string that you assigned to describe the resource.
`attributes` Optional	post string PII MTL: 30 DAYS The JSON Object string that stores application-specific data. If attributes have not been set, `{}` is returned.
`role_sid` Optional	post sid<RL> Not PII The SID of a service-level Role to assign to the user.
`x_twilio_webhook_enabled` Header	post ienum:webhook_enabled_type Not PII The X-Twilio-Webhook-Enabled HTTP request header

Example 1

Loading Code Sample...

Example JSON response

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.

Create a 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.

Fetch a specific User Resource

get

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

Parameters

Parameters in REST API format
`sid` Path	get sid_like<US> Not PII The SID of the User resource to fetch. This value can be either the `sid` or the `identity` of the User resource to fetch.

Parameters in REST API format

sid

Path

get sid_like<US> Not PII

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

Example 1

Loading Code Sample...

Example JSON response

Fetch User

Read multiple ConversationUser resources

get

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

Example 1

Loading Code Sample...

Example JSON response

Read User

Update a ConversationUser resource

post

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

Parameters

Parameters in REST API format
`sid` Path	post sid_like<US> Not PII The SID of the User resource to update. This value can be either the `sid` or the `identity` of the User resource to update.
`friendly_name` Optional	post string PII MTL: 30 DAYS The string that you assigned to describe the resource.
`attributes` Optional	post string PII MTL: 30 DAYS The JSON Object string that stores application-specific data. If attributes have not been set, `{}` is returned.
`role_sid` Optional	post sid<RL> Not PII The SID of a service-level Role to assign to the user.
`x_twilio_webhook_enabled` Header	post ienum:webhook_enabled_type Not PII The X-Twilio-Webhook-Enabled HTTP request header

Example 1

Loading Code Sample...

Example JSON response

Example for updating the friendly_name and role_sid for a user

Update a User

Example for updating the friendly_name and role_sid for a user

Delete an User resource

delete

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

Parameters

Parameters in REST API format
`sid` Path	delete sid_like<US> Not PII The SID of the User resource to delete. This value can be either the `sid` or the `identity` of the User resource to delete.
`x_twilio_webhook_enabled` Header	delete ienum:webhook_enabled_type Not PII The X-Twilio-Webhook-Enabled HTTP request header

Parameters in REST API format

sid

Path

delete sid_like<US> Not PII

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

x_twilio_webhook_enabled

Header

delete ienum:webhook_enabled_type Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Example 1

Loading Code Sample...

Example JSON response

Delete User

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Parameters

Example 1

Create a User

Parameters

Example 1

Fetch User

Example 1

Read User

Parameters

Example 1

Update a User

Parameters

Example 1

Delete User

Need some help?

Thank you for your feedback!

Thanks for your feedback!