Rate this page:

User Identity & Access Tokens

We intend to sunset the Programmable Chat API on July 25, 2022 to focus on the next generation of chat: the Twilio Conversations API. Find out about the EOL process. We have also prepared this Migration Guide to assist in the transition from Chat to Conversations.

An identity in Chat is unique to a user and may be signed in on multiple devices simultaneously. For example, identity "" will stay synchronized on a number of endpoints including her iPhone, Android tablet and in-browser application. All destinations for the same user will receive identical channel and message notifications as well as display the same message history.

On the server, we must decide, based on the token request that was sent to us, who the user is and what they should be allowed to do. To figure out who the user is (their identity), you might use your existing login system or identity provider (e.g. using session cookies, an API token, or whatever mechanism you use to secure API requests or pages today). You might not care who a user is at all, and assign them a temporary identity as in our starter apps. Who the user is, what is their role, and how you determine that will vary from application to application.

If you determine that the user should indeed be allowed to access your Chat application, you must grant your user access to Chat and supply an identity. Here are the guidelines on how to generate JWT access tokens: Creating Access Tokens.

Programmable Chat also uses identity to track monthly usage and generate accounting reports, therefore be mindful about provisioning a reasonable amount of unique identities. Reusing identities too frequently and keeping uniqueness low may cause conflicts in the user and application logic. On the other end, using only random identities will result in a large number of redundant unique users, which also impacts monthly billing.

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

Active Users in Chat

Twilio's Programmable Chat tracks unique user identities each month, and each unique identity connecting to a Chat Service will create a User record. During a calendar month, if a user registers activity, they are considered "active." The following activities register users as "active users":

  • User is created via the REST API
  • User is updated via the REST API
  • User authenticates via the SDK
  • User sends a message from the SDK
  • User sends a message from SDK
  • A message is sent on behalf of a user from the REST API
  • User joins a Channel via the SDK
  • User is added to a Channel via REST API or SDK
  • User is invited to a Channel
  • User is removed from a channel via REST or SDK

To minimize costs related to active users:

  • avoid creating the Chat client object (in the SDK) until you are certain that the User wants to read/send messages
  • avoid unnecessary REST API updates to users (e.g., User attributes)

Rate this page:

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 Community Forums or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more