Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Rate this page:
On this page

SDK Overview

Twilio provides a client-side SDK for browser-based development, as well as SDKs for native development on iOS and Android.

Our SDKs provide a convenient collection of objects, methods, and events to connect your client-side application to Conversations.

For the most up-to-date installation methods, version history, and documentation, please check out:

Initialization

initialization page anchor

Initializing the Conversations SDKs is an important step to ensure your client is ready to use on an end user's mobile or web device.

To get started, you'll need to initialize a new Client object. You'll need to pass a valid Access Token to the client creation method as the first parameter.

After that, you should listen for the client to inform you when it's fully initialized/synchronized.

Once you receive this confirmation, the client is ready to use!

Client Initialization

client-initialization page anchor
Node.js
Typescript

_14
/* Initialization */
_14
import {Client} from "@twilio/conversations";
_14
_14
const client = new Client("token");
_14
client.on("stateChanged", (state) => {
_14
if (state === "failed") {
_14
// The client failed to initialize
_14
return;
_14
}
_14
_14
if (state === "initialized") {
_14
// Use the client
_14
}
_14
});

Token Events

token-events page anchor
(information)

Info

If the token expires before you renew it, the client's connection state will change to disconnected, and you'll need to initialize a new client object.

All tokens have a limited lifetime to protect you from abuse. The maximum and default lifetime is 24 hours, but you should make it as short as possible for your application. Therefore, you may need to renew the token during your SDK session. The SDK will notify you when the token is "about to expire" and when it "has expired".

To avoid needing to instantiate a new client, you should get a new token from your server and pass it to the client's updateToken method before the old one expires. This method will update the authentication token for your client and re-register with the Conversations services.

Token Events

token-events-1 page anchor

Watch for expiration events and update your token in time

Node.js
Typescript

_30
/* Handling token expiration/expiration warning events */
_30
_30
client.on("tokenAboutToExpire", (time) => {
_30
// token is about to expire. get a new token
_30
try {
_30
const token = (await fetch("https://placekitten.com/getToken?username=username&password=password")).data();
_30
} catch {
_30
return Error("Unable to get a token");
_30
}
_30
_30
// update the client with new token
_30
client = await client.updateToken(token);
_30
_30
// use updated client
_30
});
_30
_30
client.on("tokenExpired", () => {
_30
// get a new token
_30
try {
_30
const token = (await fetch("https://placekitten.com/getToken?username=username&password=password")).data();
_30
} catch {
_30
return Error("Unable to get a token");
_30
}
_30
_30
// token expired. create a new client
_30
client = new Client(token);
_30
});
_30
_30
// update the token used by the client and re-register with the Conversations services
_30
await client.updateToken("token");

Client Connection State

client-connection-state page anchor
(information)

Info

There is a reconnection attempt period when the network connectivity is lost before the client switches to the disconnected state.

During use, the connection state of your SDK client may change.

These are the possible client connection states:

  • connecting - the client is offline a and connection attempt is in progress
  • connected - client is online and ready
  • disconnecting - the client is going offline as disconnection is in progress
  • disconnected - the client is offline and no connection attempt is in progress
  • denied - client connection is denied because of an invalid JSON Web Token access token. The user must refresh the token in order to proceed

The above-mentioned states are also documented in our SDK reference docs.

The client state changes are due to different factors. For instance, let's take the disconnected state as an example. This could happen due to a network disruption, expired token, or other error. You can listen to the client's connection state events to detect this and respond accordingly.

Handling Client State

handling-client-state page anchor
Node.js
Typescript

_10
/* Handle client state change */
_10
_10
client.on("connectionStateChanged", ({state}) => {
_10
// handle new connection state
_10
});

Enable Debugging

enable-debugging page anchor

As you build out your Conversations application, you might find it helpful to check the Twilio Console debugger(link takes you to an external page). This service aggregates all additional errors or warnings that may be triggered from Twilio's webhooks to your server, as well as token errors.

You can also enable debug logging by passing an option for increased log verbosity to your client when you create it. Check the auto-generated docs or Error Handling and Diagnostics for platform-specific examples.

What's Next?

whats-next page anchor

Congratulations! 🎉 You have now learned how to configure your Conversations SDK client! As a following step, you can:

Rate this page: