Getting started

Getting started

The SDK has the following requirements:

• Minimum Android version: API level 21 (Lollipop/5.0)

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.5.0'
       implementation group: 'com.zendesk', name: 'messaging', version: '5.5.0'
       ...
   }

   Note: messaging doesn't refer to the messaging channel, this is the name of the Classic SDK UI.

   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.5.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. The app identifier is only needed if you are configuring your app for push notifications.

//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 the ChatProvidersConfiguration:

VisitorInfo visitorInfo = VisitorInfo.builder()
                                 .withName("Bob")
                                 .withEmail("[email protected]")
  .withPhoneNumber("123456") // numeric string
  .build();

ChatProvidersConfiguration chatProvidersConfiguration = ChatProvidersConfiguration.builder()
				.withVisitorInfo(visitorInfo)
				.withDepartment("Department Name")
				.build();

Chat.INSTANCE.setChatProvidersConfiguration(chatProvidersConfiguration)

This will set a default VisitorInfo and department to be used for each ChatSession. It will also disable fields in the PreChatForm that already have information set. This data will be persisted as long as the app is alive. To clear this use:

Chat.Instance.resetIdentity();

The chat can also 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);

Note: Neither setDepartment nor setVisitorInfo will hide fields in the PreChatForm or override the information stored in ChatProvidersConfiguration. If you use these methods for setting user information you need to disable those fields on the PreChatForm manually. These methods will not persist the data, and will need be called again for consequent ChatSessions.

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.withTranscriptEnabled(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);

Important: If the Chat SDK is used in conjunction with the Answer Bot SDK, the Answer Bot SDK must be added before the Chat SDK. See Running the engine with other engines in the Chat engine docs.

Note: Starting with Messaging 5.3.0, the dependency of zendesk.messaging.MessagingActivity has changed to zendesk.classic.messaging.MessagingActivity. Note: messaging doesn't refer to the messaging channel, this is the name of the Classic SDK UI.

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 withOfflineFormEnabled 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 chat session will terminate if any of the following conditions are met:

• The visitor without push has been idle* for more than 20 minutes (30 minutes total).
• The visitor with push has been inactive for more than 5 minutes.
• The visitor has been disconnected for the duration of the inactivity timeout (30 minutes or 5 minutes).
• The agent ends the chat, at which point the session will terminate after 5 minutes without visitor input, regardless off whether push notifications have been configured. Any new message will place you back in the queue.
• The visitor ends the chat, at which point the session will immediately terminate.
• On the Agent Workspace account, if either the visitor or the agent ends the chat, the session will immediately terminate.

*The visitor will become idle after no input is detected for 10 minutes.

Advanced Topics

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