Using the Chat SDK API providers

Using the Chat SDK API providers

The Chat SDK API providers encapsulate all of the functionality of the Chat SDK from setting visitor information to more advanced functionality like observing certain events that can occur during a chat.

If you wish to build your own UI, you can use these providers to implement functionality such as sending messages on behalf of the visitor.

Using the API providers alongside the Chat SDK

Please be aware, the Chat SDK has its own connection management, based on the lifecycle of the Activity provided by the Unified SDK. This is important if you are using the Chat API providers alongside the Chat SDK. The ownership of the connection life-cycle outside of the Chat screen, is in your own hands.

Important: Before using the API providers, make sure you call connect, and set up a connection status observer to handle the connection state appropriately. This is required for Chat to work properly.

connectionProvider.connect();

connect can be called before or after the rest of your API calls. This is because all API requests go into an operation queue. Once a connection is established, the requests are sent in sequence.

You can observe the status of the connection with the following:

connectionProvider.observeConnectionStatus(new ObservationScope(), new Observer<ConnectionStatus>() {
            @Override
            public void update(ConnectionStatus connectionStatus) {
                if (connectionStatus == ConnectionStatus.CONNECTED) {
                    //Your code
                }
            }
        });

Remember to call disconnect before any flow that brings the user back to the chat screen.

connectionProvider.disconnect();

Accessing the providers

Providers can be accessed from the Chat singleton:

Chat.INSTANCE.providers().chatProvider();
Chat.INSTANCE.providers().profileProvider();

Observing events

The providers allow you to observe certain events that can occur. The methods take an ObservationToken and an Observer. Example:

ObservationScope observationScope = new ObservationScope();
Chat.INSTANCE.providers().chatProvider().observeChatState(observationScope, new Observer<ChatState>() {
            @Override
            public void update(ChatState chatState) {
                //Do something with chat state
            }
        });

It's important that if you start observing these events that you also remember to stop observing them:

observationScope.cancel()

Getting the availability of agents

You can check the availability of agents and departments:

accountProvider().getAccount(new ZendeskCallback<Account>() {
        @Override
        public void onSuccess(Account account) {
            // Insert your account handling code here
        }

        @Override
        public void onError(ErrorResponse errorResponse) {
            // Handle error in getting Account here
        }
});

For details about the Account class, see the reference docs.

You can also observe changes to the availability of agents:

accountProvider().observeAccount(ObservationScope observationScope,
                                 Observer<Account> observer);

Observing changes to Chat settings

You can be notified of any changes that are made to the settings in the Chat dashboard:

settingsProvider().observeChatSettings(ObservationScope observationScope, Observer<ChatSettings> observer);

For details about the ChatSettings class, see the reference docs.

Observing the connection state

You can listen for connection state changes:

connectionProvider.observeConnectionState(ObservationScope observationScope,
                                          Observer<ConnectionState> observer);

Observing the chat state

You can observe the state of the chat, and gather information about the session:

chatProvider.observeChatState(ObservationScope observationScope,
                              Observer<ChatState> observer);

The ChatState object has the following properties:

Property	Description
agents	List of agents in the chat.
logs	Array of ChatLog items that represent the messages in the conversation.
queuePosition	The visitor's current queue position.
isChatting	Whether the visitor has started chatting with an agent.
department	Department requested by the visitor.
chatSessionStatus	The phase of the current chat session. See the reference docs.
rating	The rating of the current session given by the visitor.
comment	The rating comment of the current session given by the visitor.

For details about the ChatState class, see the reference docs.

Sending a message

chatProvider().sendMessage(String message)

You can try resending or deleting a failed message with the following methods, which take the chatLogId as an argument:

chatProvider().deleteFailedMessage(String failedChatLogId);

chatProvider().resendFailedMessage(String failedChatLogId);

Sending an attachment

An attachment can be sent by providing a File, and the FileUploadListener will provide the progress of the upload.

chatProvider().sendFile(File file, FileUploadListener fileUploadListener);

The following example uses the provider's sendFile() method to send an image from the assets folder:

private void sendImageFromAssets(){
    try {
        File tempFile = createTempFile(".png", context.getCacheDir());
        InputStream inputStream = context.getAssets().open("zenchat.png");
        OutputStream outputStream = new FileOutputStream(tempFile.getPath());
        if (inputStream != null) {
            syncIoStream(inputStream, outputStream);
            chatProvider().sendFile(tempFile, new FileUploadListener() {
                @Override
                public void onProgress(String chatLogId, long bytesUploaded, long contentLength) {
                    Log.d(LOG_TAG, "Upload: id: " + chatLogId + ", " + bytesUploaded + "/" + contentLength + ")");
                }
            });
        }
    } catch (IOException ex) {
        Log.e(LOG_TAG, ex.getMessage());
    }
}

private File createTempFile(String extension, File directory) throws IOException {
    return File.createTempFile("temp-" + extension.replace(".", ""), extension, directory);
}

private void syncIoStream(InputStream inStream, OutputStream outStream) throws IOException {
    byte[] b = new byte[inStream.available()];
    inStream.read(b);
    outStream.write(b);
    inStream.close();
    outStream.close();
}

You can resend or delete a file with the following methods, which take the chatLogId as an argument:

chatProvider().resendFailedFile(String chatLogId, FileUploadListener fileUploadListener);

chatProvider().deleteFailedMessage(String failedChatLogId);

Ending a chat

You can end a chat at any point and use the callback to verify whether it was successful.

chatProvider().endChat(ZendeskCallback<Void> callback)

Adding and removing tags

To append a specific tag:

profileProvider().addVisitorTags(List<String> tags, ZendeskCallback<Void> callback);

To remove a tag that has already been added:

profileProvider().removeVisitorTags(List<String> tags, ZendeskCallback<Void> callback);

If you need to clear all tags that have been added to a chat, you will need to keep track of each possible tag.

Sending a chat rating

chatProvider().sendChatRating(ChatRating chatRating, ZendeskCallback<Void> callback);

Sending a chat comment

chatProvider().sendChatComment(String chatComment, ZendeskCallback<Void> callback);

Sending an offline message

This method should only be used to send an offline message to an offline account or department. A new chat is created every time this method is called. If your Chat account is linked to a Support account, a ticket will automatically be created for each message.

VisitorInfo visitorInfo = VisitorInfo.builder()
                                 .withName(String name)
                                 .withEmail(String email);

OfflineForm offlineForm = OfflineForm.builder(String message)
                                     .withVisitorInfo(visitorInfo)
                                     .withDepartmentName(String departmentName);

chatProvider().sendOfflineForm(OfflineForm offlineForm, ZendeskCallback<Void> callback);

Checking for info about an ongoing chat

You can check if there's already an ongoing conversation before starting the chat.

Note: This API proactively connects to web sockets for authenticated users. This connection is kept alive. You should call disconnect() on the ConnectionProvider if you don't need to keep it open.

chatProvider().getChatInfo(ZendeskCallback<ChatInfo> callback);