Getting started

The SDK has the following requirements:

  • Minimum Android version: API level 16 (Jelly Bean / 4.1)

Add the Chat SDK dependencies

Adding the SDK with Gradle
  1. In Android Studio, open the build.gradle file for the app module (not for the project).

  2. Before the dependencies section, add the following repositories section:

    repositories {
        maven { url 'https://zendesk.jfrog.io/zendesk/repo' }
    }
    
  3. If you plan on using the SDK's built-in UI components, insert the following lines in the dependencies section:

    dependencies {
        implementation group: 'com.zendesk', name: 'chat', version: '3.0.0'
        implementation group: 'com.zendesk', name: 'messaging', version: '5.0.0'
        ...
    }
    

    If you only want to use the SDK's API providers and no UI components, insert the following line instead in the dependencies section:

    dependencies {
        implementation group: 'com.zendesk', name: 'chat-providers', version: '3.0.0'
        ...
    }
    

    Note: If you plan on using both the API providers and the UI components, specify 'chat' as the name. This gives you both.

  4. Save the file, then integrate the Chat SDK in the project by selecting File > Sync Project with Gradle Files.

Initializing the SDK

The Chat SDK initialization should take place in the onCreate() method of your Application class. The initialization method takes a Context, your account key, and your app identifier. These can be obtained by asking the account owner.

//BaseApplication.java
Chat.INSTANCE.init(applicationContext, "Your account key", "Your app identifier");

Configuring the SDK

Configuring the conversation

The Chat SDK provides ChatConfiguration.Builder that you can use to enable or disable certain conversational features.

ChatConfiguration chatConfiguration = ChatConfiguration.builder()
    .withAgentAvailabilityEnabled(false)
    .build();

For the full documentation on the ChatConfiguration builder methods, see Customizing the look.

Setting information for the chat session

The chat can be configured using either the ProfileProvider or the ChatProvider class.

ProfileProvider profileProvider = Chat.INSTANCE.providers().profileProvider();
ChatProvider chatProvider = Chat.INSTANCE.providers().chatProvider();

VisitorInfo visitorInfo = VisitorInfo.builder()
                                 .withName("Bob")
                                 .withEmail("[email protected]")
                                 .withPhoneNumber("123456") // numeric string
                                 .build();
profileProvider.setVisitorInfo(visitorInfo, null);
chatProvider.setDepartment("Department name", null);
ProfileProvider
Setting Description
setVisitorInfo Allows the visitor's name, email address and phone number to be specified. This will be seen by the agent. See VisitorInfo.
addVisitorTags Adds a list of tags which will then appear to the agent in the chat.
removeVisitorTags Removes an array of tags that have already been added.
setVisitorNote Sets the note on the visitor profile.
appendVisitorNote Appends the note to an existing note on the visitor profile.
clearVisitorNote Clears all visitor notes.
trackVisitorPath Used to track navigation history.
getVisitorInfo Gets the currently cached information about the visitor
observeVisitorInfo Registers an observer to be notified when the visitor information changes.
VisitorInfo

You can create an instances of VisitorInfo with a dedicated builder as follows:

VisitorInfo visitorInfo = VisitorInfo.builder().build();

Visitor information can be configured with the following builder methods:

Setting Description
withName Sets the name that will be associated with the visitor.
withEmail Sets the email that will be associated with the visitor.
withPhoneNumber Sets the phone number that will be associated with the visitor.
ChatProvider
Setting Description
setDepartment This can be set to a valid string that matches the name of a department configured in the Chat dashboard. The chat will then be routed accordingly. For more information about getting a list of available departments, see Getting the availability of agents.

Important: The department can't be updated once a session has started but VisitorInfo and tags can be updated throughout a session.

Disabling chat transcripts

Disabling chat transcripts can be done by doing the following in the ChatConfiguration:

chatConfiguration.withChatTranscriptsEnabled(false)
                             .withMenuItems(ChatMenuAction.END_CHAT);

Alternatively withMenuItems() can also be used to remove the menu from the conversation screen.

Important: If you're setting a department while also using a trigger to send an initial message, please see here for related information.

Starting a chat

Starting a chat begins with building the messaging interface, and this requires at least one product engine to be passed in. See the Unified SDK documentation for more details about product engines and how to use them.

MessagingActivity.builder()
    .withEngines(ChatEngine.engine())
    .show(view.getContext(), chatConfiguration);

Push Notifications

You can use push notifications with the Chat SDK to notify your users every time the agent sends a new message to the conversation. To learn how to enable the push notifications in your app, see Push Notifications.

Enabling offline forms

Offline forms provide a way for your visitors to contact you when all of your agents are offline. The form supports name and email input, where the email field is required to complete the form. It will create a ticket on your support dashboard once submitted. Offline forms can be enabled or disabled by setting withOfflineFormsEnabled in the ChatConfiguration.Builder class. The isAgentAvailabilityEnabled flag needs to be enabled for offline forms to work. For more details, see Customizing the Chat experience.

Configuring the queue

The queue provides a way for users to see a rough estimate of how long they will be waiting to talk to an agent. It is based on the number of other visitors ahead of them. It is not possible to disable the queue, but it is possible to change or remove the text. See known issues for more information.

Logging

Logging is disabled by default, but you can enable it as follows:

Logger.setLoggable(true)

Session termination

The inactivity timeout for a session lasts for 1 hour if you have configured push notifications or for 5 minutes if you have not.

The chat session will terminate if any of the following conditions are met:

  • There's no activity on the chat for the duration of the inactivity timeout (1 hour or 5 minutes)
  • The visitor has been disconnected for the duration of the inactivity timeout
  • The agent ends the chat, at which point the session will terminate after 5 minutes, regardless off whether push notifications have been configured
  • The visitor ends the chat, at which point the session will immediately terminate

Advanced Topics

See the documentation of our APIs for descriptions of classes and models.