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.
Once your Conversations Client is fully synchronized at client startup, the following is applicable:
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:
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 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:
FriendlyName
,
UniqueName
, and
Attributes
for each Subscribed Conversation in the list
To load Messages for a Subscribed Conversation and subscribe to other Conversation-level events you will need to load individual Conversations manually.
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:
The Conversations Client is instantiated in one of two ways:
You can use promises directly:
1Conversations.Client.create(token).then(client => {2// Use client3});
Or using the async/await pattern:
1let client = await Twilio.Conversations.Client.create(token);2// Use client
First, we initialize the Conversations Client. Here we provide an initial Access Token:
1NSString *token = <token goes here>;2__weak typeof(self) weakSelf = self;3[TwilioConversationsClient conversationsClientWithToken:token4properties:nil5delegate:<delegate>6completion:^(TCHResult *result, TwilioConversationsClient *convoClient) {7weakSelf.client = convoClient;8... }];
The iOS Conversations SDK then provides a TCHClientSynchronizationStatus
delegate callback:
1- (void)conversationsClient:(TwilioConversationsClient *)client2synchronizationStatusUpdated:(TCHClientSynchronizationStatus)status {3if (status == TCHClientSynchronizationStatusCompleted) {4// Client is now ready for business5}6}
The Android Conversations SDK provides a Listener Interface which you must implement to check the init status and completion of the SDK client.
1ConversationsClient.Properties props = ConversationsClient.Properties.newBuilder().createProperties();23ConversationsClient.create(context.getApplicationContext(),4accessToken,5props,6new CallbackListener<ChatClient>() {7@Override8public void onSuccess(final ConversationsClient client) {9// save client for future use here10client.addListener(new ConversationsClientListener() {11@Override12public void onClientSynchronization(ConversationsClient.SynchronizationStatus status) {13if (status == ConversationsClient.SynchronizationStatus.COMPLETED) {14// Client is now ready for business, start working15}16}17});18}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.