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.
Initializing Programmable Chat SDKs is an important step to ensure your client is ready to be used by the user. SDKs help put necessary data in place and set up event handlers for new messages and other events.
Once your Chat Client is fully synchronized at client startup:
You must maintain a strong reference to the client object you received, keeping it in scope for the entirety of your usage of the Chat Client.
Before releasing the client it is important to release references to all objects created and returned by this Chat Client (i.e. set all objects to nil
) and to call the shutdown
method of the client to ensure proper cleanup of shared resources.
No previously existing Messages are fetched for the client on load. These will be loaded when you call the getMessages
method to fetch messages on demand. Messages are then cached and updated after loading.
You receive feedback on client startup in two ways:
create
client method when the client has been successfully created and is being synchronized.synchronizationStatusUpdated
method with a value of StatusCompleted
. This is your indication the client is ready for business, and all User Channels have been obtained and subscribed to.The JavaScript client will retrieve the list of Subscribed Channels that a User is a Member of (or has been invited to) once that user logs into the client.
Some additional details on the JavaScript SDK behavior:
FriendlyName
, UniqueName
, and Attributes
for each Subscribed Channel in the listTo load Messages for a Subscribed Channel and subscribe to other Channel-level events you will need to load individual Channels manually. More information on this can be found in the Channels and Messages guide.
It is important to know when the SDK Client has completed its initialization and is ready for use. Once the client is connected, you can configure all your listeners, event handlers, and other logic.
This manifests slightly differently for each SDK as detailed below:
The Chat Client is instantiated in one of two ways:
1Twilio.Chat.Client.create(token).then(client => {2// Use client3});
Or asynchronously, waiting for the result:
1let client = await Twilio.Chat.Client.create(token);2// Use client
First, we initialize the Chat Client. Here we provide an initial Access Token:
1NSString *token = <token goes here>;2__weak typeof(self) weakSelf = self;3[TwilioChatClient chatClientWithToken:token4properties:nil5delegate:<delegate>6completion:^(TCHResult *result, TwilioChatClient *chatClient) {7weakSelf.client = chatClient;8... }];
The iOS Chat SDK then provides a TCHClientSynchronizationStatus
delegate callback:
1- (void)chatClient:(TwilioChatClient *)client2synchronizationStatusUpdated:(TCHClientSynchronizationStatus)status {3if (status == TCHClientSynchronizationStatusCompleted) {4// Client is now ready for business5}6}
The Android Chat SDK provides a Listener Interface which you must implement to check the init status and completion of the SDK client.
1ChatClient.Properties props = new ChatClient.Properties.Builder()2.createProperties();34ChatClient.create(context.getApplicationContext(),5accessToken,6props,7new CallbackListener<ChatClient>() {8@Override9public void onSuccess(final ChatClient client) {10// save client for future use here11client.setListener(new ChatClientListener() {12@Override13public void onClientSynchronization(ChatClient.SynchronizationStatus status) {14if (status == ChatClient.SynchronizationStatus.COMPLETED) {15// Client is now ready for business, start working16}17}18});19}20});
Before we get too much deeper into showing how to get your users chatting, it's important to know where to look for logs and additional information if you need it. We have a guide about Error Handling and Diagnostics and Programmable Chat you may find helpful as you build your Chat integration.
All Chat SDK clients need a valid Access Token to be able to authenticate and interact with the Chat Service. The Access Token is generated on your server - you can learn more about how to do that in the Access Token guide.
The Access Token returned by your backend must be used when instantiating the SDK Client. You will pass the Token string directly to the SDK Client constructor method.
The SDK also provides a method to update the Access Token, which is used when you need to update the Access Token before expiration. Please see the Creating Access Tokens guide for more information.
Next: Creating Access Tokens