Programmable Chat has been deprecated and is no longer supported. Instead, we'll be focusing on the next generation of chat: Twilio Conversations. Find out more about the EOL process here.
If you're starting a new project, please visit the Conversations Docs to begin. If you've already built on Programmable Chat, please visit our Migration Guide to learn about how to switch.
Programmable Chat is a cloud-based chat product which provides a number of client SDKs and a REST API for use in integrating Chat capabilities into applications and websites.
Programmable Chat has several core data types or objects which you will interact with:
Chat Services are where all the Channels, Messages, Users and other resources within a Chat deployment live. Services are entirely siloed, and while you can have many Services in an Account, Services do not overlap or interact in any way.
Note: To interact with Chat, you will need to create a Chat Service instance for your SDKs to connect to, and for your backend to be able to control via REST. You can create and configure Chat Service instances in the following places and ways:
Programmable Chat is a user-centric system, and each unique identity connecting to a Chat Service will create a User record. You can read more about user identities and access tokens as well as "active users."
Within a Chat Service, Users can interact in different ways with the Service itself as well as with Channels, Messages, Users, and Members. A User's Role determines their permissions within a Service and various Channels.
Channels are the heart of all chat activity within a Service. Channel Members send Messages to the Channel, which are then distributed to other Members of the Channel. Channels can be private or public .
Private Channels are not visible to Users that have not been invited or added to them. Private Channel Members can only be added by other Members with sufficient permissions, or via the REST API as controlled by your business logic.
Public Channels can generally be browsed and joined by any Users within the Service.
A User within a Service can interact with Channels as a Member. Members have an assigned Role within a given Channel that dictates what the Member can do within that Channel.
All chat Messages exist within a Service as part of a Channel. Messages are stored in order, and all Members of a Channel can access Messages and create new ones. Note that Member permissions can be modified to limit the actions and data allowed within a Channel via their assigned Role.
Messages can also be edited and removed (subject to Role permissions).
The Chat REST API is used by your backend services and is intended for system usage. The API can be used to orchestrate the usage of Programmable Chat - such as creating a private Channel and adding a customer support agent User as a Member along with the customer User.
Your backend logic can control virtually every aspect of a Service including creating Channels, adding or removing Users and Members, sending Messages and more.
The Programmable Chat SDKs have many shared fundamentals which are important for you to understand to ensure best practices and proper usage. This guide introduces these fundamentals and aims to provide code samples for each SDK.
Twilio's Chat SDKs are used to build 1st person chat experiences in mobile and web applications. These experiences are designed to be user-centric, authenticated and identified by your backend.
All access and interactions from the Chat SDK client endpoints happen in the context of this user identity interacting with Channels and Messages on the Chat Service. It is therefore important for your application to perform any necessary authentication or authorization of the User before generating an Access Token for their identity .
The SDKs interact with the Chat Service over a websocket connection which is established and maintained by the SDK. Communication with the Chat Service is in real time and is bidirectional in nature. The following protocols and hostnames are used to communicate with Twilio's cloud. If necessary, use this information to configure your firewall to enable communication with Twilio.
| Region ID | Location | Host Name | Port and Protocol |
|---|---|---|---|
| us1 | US East Coast (Virginia) | wss://tsock.us1.twilio.com | 443 WSS (websocket over TLS) |
| us1 | US East Coast (Virginia) | https://media.us1.twilio.com | 443 HTTPS (HTTP over TLS) |
| us1 | US East Coast (Virginia) | https://mcs.us1.twilio.com | 443 HTTPS (HTTP over TLS) |
Unfortunately, at this moment it is not possible to use static IP addresses due to the nature of the load balancing setup. In case an allow-list is required, it is still possible to enable a larger range of Amazon Web Service IP addresses.
To interact with a Chat Service from an SDK client, a valid Access Token is needed. This Access Token is generated by your backend using the relevant Twilio Helper Library and is cryptographically signed to ensure the contents are trusted by the Chat Service.
You will also need to implement the Token refresh logic if your client uses Access Tokens that are shorter lived than your Chat Client sessions. The optional AccessManager helper is available for all platforms and can assist with this.
Read more about how to generate Access Tokens and managing Token lifecycles.
The Chat SDKs all follow an asynchronous model of interaction with the Chat Service. This means that commands from the SDK clients do not block synchronously while waiting for the final result of the command (although they will receive a response from the Service upon command acceptance). Instead, event handlers (callback handlers/listeners) must be implemented on the client side to receive and process the asynchronous responses from the service.
Each SDK has a particular mechanism for asynchronous event handlers:
Examples of how these work in various places within the Chat SDKs are found in the more specific guides which follow.
Next: Initializing the SDKs