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

Initializing Conversations SDK Clients


Initializing Conversations SDKs is an important step to ensure your client is ready for use on an end user's mobile or web device. The Conversations SDKs put necessary data in place and set up event handlers for new Messages and other events.

This guide covers how to initialize the Conversations SDKs, both for mobile and web.


Mobile SDKs (Android and iOS)

mobile-sdks-android-and-ios page anchor

Once your Conversations Client is fully synchronized at client startup, the following is applicable:

  • The client is subscribed to events for all of the Participant's Conversations .
  • The Messages and Participants collections are available for querying.
(information)

Info

You must maintain a strong reference to the client object you received, keeping it in scope for the entirety of your usage of the Conversations Client.

Before releasing the client, it is important to release references to all objects created and returned by this Conversations Client (i.e., set all objects to nil) and to call the client's shutdown method 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.

Note: For the getMessages method, the default pageSize value is 30 and the maximum pageSize value is 100.

You receive feedback on client startup in two ways:

  • You will receive an asynchronous callback from the create client method when the client has been successfully created and is being synchronized.
  • You will receive an event to the client's listener or delegate via the synchronizationStatusUpdated method with a value of StatusCompleted . This is your indication that the client is ready for business and that all of the Participant's Conversations have been obtained and subscribed to.

Once a user logs into the client, the JavaScript client will retrieve the list of Subscribed Conversations in which the user is a Participant.

Some additional details on the JavaScript SDK behavior:

  • It will subscribe to notifications for changes to the Subscribed Conversations list itself
  • It will subscribe to events from each Subscribed Conversation in the list
  • It will retrieve the FriendlyName , UniqueName , and Attributes for each Subscribed Conversation in the list
  • It will not retrieve any Messages for individual Conversation
  • It will retrieve Participant lists for Conversations
  • It will not retrieve, nor subscribe to Users linked to Participants of Subscribed Conversations
  • It will retrieve a currently logged-in User object and subscribe to this User's events

To load Messages for a Subscribed Conversation and subscribe to other Conversation-level events you will need to load individual Conversations manually.


Knowing when the SDK is ready for use

knowing-when-the-sdk-is-ready-for-use page anchor

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 your listeners, event handlers, and other logic.

This manifests slightly differently for each SDK as detailed below:

JavaScript

javascript page anchor

The Conversations Client is instantiated in one of two ways:

You can use promises directly:


_10
Conversations.Client.create(token).then(client => {
_10
// Use client
_10
});

Or using the async/await pattern:


_10
let client = await Twilio.Conversations.Client.create(token);
_10
// Use client

First, we initialize the Conversations Client. Here we provide an initial Access Token:


_10
NSString *token = <token goes here>;
_10
__weak typeof(self) weakSelf = self;
_10
[TwilioConversationsClient conversationsClientWithToken:token
_10
properties:nil
_10
delegate:<delegate>
_10
completion:^(TCHResult *result, TwilioConversationsClient *convoClient) {
_10
weakSelf.client = convoClient;
_10
... }];

The iOS Conversations SDK then provides a TCHClientSynchronizationStatus delegate callback:


_10
- (void)conversationsClient:(TwilioConversationsClient *)client
_10
synchronizationStatusUpdated:(TCHClientSynchronizationStatus)status {
_10
if (status == TCHClientSynchronizationStatusCompleted) {
_10
// Client is now ready for business
_10
}
_10
}

The Android Conversations SDK provides a Listener Interface which you must implement to check the init status and completion of the SDK client.


_19
ConversationsClient.Properties props = ConversationsClient.Properties.newBuilder().createProperties();
_19
_19
ConversationsClient.create(context.getApplicationContext(),
_19
accessToken,
_19
props,
_19
new CallbackListener<ChatClient>() {
_19
@Override
_19
public void onSuccess(final ConversationsClient client) {
_19
// save client for future use here
_19
client.addListener(new ConversationsClientListener() {
_19
@Override
_19
public void onClientSynchronization(ConversationsClient.SynchronizationStatus status) {
_19
if (status == ConversationsClient.SynchronizationStatus.COMPLETED) {
_19
// Client is now ready for business, start working
_19
}
_19
}
_19
});
_19
}
_19
});


Before we dive deeper into showing how to get your Participants engaged through different channels, 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 that you may find helpful as you build your Conversations integration.


All Conversations SDK clients need a valid Access Token in order to authenticate and interact with the Chat Service instance. You should generate the Access Token on your server. You can learn more about how to do that in the Access Token guide.

When instantiating the SDK client, you should use the Access Token that is returned by your backend. 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.


Now that you've gotten your SDK initialized on the client, check out the rest of the Conversations documentation.


Rate this page: