SDK Overview

To initialize the Conversations (classic) SDK, create a new Client object and pass a valid Access Token to the client creation method as the first parameter.

After that, listen for the client to inform you when it's fully initialized and synchronized. Once you receive this confirmation, the client is ready to use.

1
/* Initialization */
2
import { Client } from '@twilio/conversations';
3

4
const client = new Client('token');
5
client.on('stateChanged', (state) => {
6
  if (state === 'failed') {
7
    // The client failed to initialize
8
    return;
9
  }
10

11
  if (state === 'initialized') {
12
    // Use the client
13
  }
14
});

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 (classic) services.

1
/* Handling token expiration/expiration warning events */
2

3
client.on("tokenAboutToExpire", (time) => {
4
    // token is about to expire. get a new token
5
    try {
6
        const token = (await fetch("https://placekitten.com/getToken?username=username&password=password")).data();
7
    } catch {
8
        return Error("Unable to get a token");
9
    }
10

11
    // update the client with new token
12
    client = await client.updateToken(token);
13

14
    // use updated client
15
});
16

17
client.on("tokenExpired", () => {
18
    // get a new token
19
    try {
20
        const token = (await fetch("https://placekitten.com/getToken?username=username&password=password")).data();
21
    } catch {
22
        return Error("Unable to get a token");
23
    }
24

25
    // token expired. create a new client
26
    client = new Client(token);
27
});
28

29
// update the token used by the client and re-register with the Conversations services
30
await client.updateToken("token");

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

These are the possible client connection states:

• connecting- the client is offline and a connection attempt is in progress
• connected - the 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 - the client connection is denied because of an invalid JSON Web Token access token. The user must refresh the token in order to proceed

These states are also documented in the SDK reference docs.

Client state changes are due to different factors. For example, the disconnected state can result from a network disruption, an expired token, or another error. You can listen to the client's connection state events to detect this and respond accordingly.

1
/* Handle client state change */
2

3
client.on('connectionStateChanged', ({ state }) => {
4
  // handle new connection state
5
});

As you build your Conversations (classic) application, you might find it helpful to check the Twilio Console debugger. 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.

After configuring your Conversations (classic) SDK client, you can:

• Learn how to handle events, or
• Check out our Working with Conversations (classic) guide