Chat SDK for Android Quick Start

This hands-on tutorial shows you how to build a functioning Android application in 30 minutes that lets users chat with a support agent. It uses the Zendesk Chat SDK for Android, a shared code library that lets you easily incorporate Zendesk Chat in Android applications.

Zendesk gives you other options for providing customer support in mobile apps:

• You can use the Support SDK to incorporate other Zendesk customer support features in Android applications. To learn how, see Quick start - Support SDK for Android.

• You can use the Unified SDK to incorporate Zendesk bots with Chat and Support to create a unified messaging experience.

You need Android Studio to build the small Android application in this tutorial. You can download Android Studio from the Android developer website.

You'll also need a Zendesk Chat account. A free trial account is available. See the Zendesk Chat website.

Though this quick start guide provides step-by-step instructions to build a simple application, it's not an Android app tutorial, If you're new to Android development, I highly recommend working through the lessons in Build Your First App on the Android website.

The guide walks you through the following basic steps for adding chat functionality to an Android application:

1. Creating a sample project
2. Adding the Chat SDK to the project
3. Initializing the framework
4. Creating a button to start a chat
5. Adding an event listener for the Chat button
6. Testing that chat works
7. Next steps

The tutorial uses version 3.3.6 of the Chat SDK. It was tested using Android Studio 2021.2.1 (Chipmunk).

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk can't provide support for third-party technologies such as Java, Android, and Android Studio. Please post any issue in the Zendesk SDKs community, or search for a solution online.

Creating a sample project

This section shows you how to create a quick sample project in Android Studio. You'll use the project to try out the Chat SDK.

1. In Android Studio, select File > New > New Project.

   If you're at the welcome window, choose Start a new Android Studio project.

2. In the Select a Project Template screen, make sure the Phone and Tablet tab is selected, click Empty Activity, and click Next.

   

3. Set the following options for the project:

   • Name - Enter My Sample Chat App or something similar
   • Package name - (required) Enter something like com.sample.mysamplechatapp
   • Save location - (required) Choose where you want to save the project
   • Language - Java
   • Minimum SDK - API 21: Android 5.0 (Lollipop)

4. Click Finish.

Android Studio creates all the files and basic settings for your project. You can view the files in the Project navigator on the left side of the screen. If you don't see the files, click the first icon (the folder icon) on the upper side of the panel.

Adding the Chat SDK to the project

Note: messaging here does not refer to the Messaging channel, but to the library used to send messages.

1. In your project files in the left sidebar, locate Gradle Scripts > build.gradle (Module: My_Sample_App.app), then double-click the file to open it in the editor.

   

   Note: Make sure not to open the first gradle file, build.gradle (Project: My_Sample_App).

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

   repositories {
       maven { url 'https://zendesk.jfrog.io/zendesk/repo' }
   }

3. In the dependencies section, insert the following line (highlighted):

   dependencies {
     implementation group: 'com.zendesk', name: 'chat', version: '3.4.0'
     implementation group: 'com.zendesk', name: 'messaging', version: '5.4.0'
     ...
   }

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

   The gradle.build file should look partially as follows:

   repositories {
       maven { url 'https://zendesk.jfrog.io/zendesk/repo' }
   }
   
   dependencies {
       implementation group: 'com.zendesk', name: 'chat', version: '3.4.0'
       implementation group: 'com.zendesk', name: 'messaging', version: '5.4.0'
       implementation 'androidx.appcompat:appcompat:1.4.1'
       implementation 'com.google.android.material:material:1.5.0'
       implementation 'androidx.constraintlayout:constraintlayout:2.1.3'
       testImplementation 'junit:junit:4.13.2'
       androidTestImplementation 'androidx.test.ext:junit:1.1.3'
       androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
   }

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

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

If you see the following error, you'll need to update your settings.gradle file as follows.

Build was configured to prefer settings repositories over project 
repositories but repository 'maven' was added by build 
file 'app/build.gradle'.

1. In your project files in the left sidebar, locate Gradle Scripts > settings.gradle, then double-click the file to open it in the editor.

2. Replace repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) with repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS).

3. In the repositories section, insert the following line (highlighted):

   repositories {
       maven { url 'https://zendesk.jfrog.io/zendesk/repo' }
       ...
   }

   The settings.gradle file should look partially as follows:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
       repositories {
           maven { url 'https://zendesk.jfrog.io/zendesk/repo' }
           google()
           mavenCentral()
        }
    }

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

   You can ignore the deprecated Gradle warning.

Running a test build

Before going any further, make sure you successfully added the Chat SDK to your project. One way is to run a test build in a phone emulator. The application doesn't do much yet, but if you don't get any build errors you know you're on the right path.

You can use the emulator that’s included in Android Studio. First, you'll need to create an Android Virtual Device (AVD) definition for the emulator. Your AVD definition will specify the characteristics of an Android phone. In this case, you'll define a Pixel phone.

1. Click the Device Manager icon on the toolbar (or select Tools > Device Manager).

2. In the Virtual Devices screen, click Create Virtual Device.

3. In the Select Hardware screen, select the latest, regular-sized Pixel phone, and then click Next.

4. In the System Image screen, click the Download link next to the latest recommended system image (Android API 32 with x86-64 ABI at the time of this writing).

   The components can take a few moments to download.

5. After the download is complete, select the system image from the list and click Next.

6. On the next screen, change the AVD Name to something like "Pixel phone", then click Finish.

7. In the Your Virtual Devices screen that appears, click the green triangle on the right side to launch this phone in the emulator:

   

   Be patient. It can take a few moments for the OS to start up the first time the system image is used.

8. Once the emulator is up and running, return to your Project window, click the Run icon (green triangle) on the toolbar (or select Run > Run 'app'), and select your Pixel phone.

   

   Eventually your sample app should open in the phone emulator:

   

The test is a success if you don't get any errors.

Initializing the framework

Before a user can use chat on their device, the application has to create and prepare an instance of the Chat SDK.

In this section, you'll update the sample application to initialize the Chat SDK and make it ready for use. The task consists of the following steps:

1. Getting the Zendesk Chat account key
2. Adding the initialization code to your application

Getting the Zendesk Chat account key

You'll need access to the Zendesk Chat dashboard to get the account key. If you don't have access, ask somebody who does to perform the following steps.

1. In the Chat dashboard, click the profile icon in the upper right, then select Check Connection.

   

2. Copy and save the account key. It should be the second item in the list.

Adding the initialization code to your application

Android applications are event driven, so you need to initialize the framework in an event handler. By default, your application comes with an onCreate(Bundle) event handler that runs when an instance of your MainActivity subclass is created. You can add your own code to this event handler.

1. Make sure the MainActivity.java file is open in the Android Studio editor. It should be open by default. If not, you'll find the file in the java/com.sample.mysamplechatapp folder.

2. Add the following initialization statement to the onCreate(Bundle) handler (highlighted):

   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
   
       Chat.INSTANCE.init(applicationContext, "your account key");
   }

   Note: Chat and applicationContext should turn red, indicating there's something wrong. You'll fix this in the next steps.

3. To fix the error indicated by the red Chat text, click anywhere in the red text, then press Option+Enter (Mac) or Alt+Enter (Windows). If prompted, select Import Class from the menu. Android Studio automatically adds the missing import statement in the top portion of the file:

   import zendesk.chat.Chat;

   The Chat text color should return to normal.

   If you prefer, you can insert the import statement manually.

4. Replace applicationContext in the init() method with this (no quotes).

5. Replace the your account key placeholder value in the init() method with the account key you retrieved earlier from the Chat dashboard.

   The onCreate() method should look as follows:

   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
   
       Chat.INSTANCE.init(this, "4PBQNia9qItVDD98qmCYEfVesWLR4IFC");
   }

6. Run a build to make sure you don't get any error messages.

Creating a button to start a chat

The chat functionality provided by the SDK is designed to start in response to an event such as a button click.

Your default sample project consists of a ConstraintLayout containing a TextView that displays "Hello World!". The application's layout is defined in the activity_main.xml file in the res/layout folder:

You'll change the layout to a vertical LinearLayout containing a single Chat button.

1. In the Project window, make sure the activity_main.xml file is open in the editor. If not, you'll find the file in the res/layout folder.

   Note: If you don't see the XML from the previous screenshot, make sure that Code on the upper right side of the window is selected.

2. Replace all the contents of the file with the following layout code:

   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       android:gravity="center"
       android:orientation="vertical" >
   
   <Button
       android:id="@+id/chat_button"
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:text="@string/chat_button" />
   
   </LinearLayout>

   Notice that the button text is a reference to a string resource: "@string/chat_button". You'll add the string resource in the next step.

3. Open the strings.xml file in the res/values/ folder and add the following <string> child tag to the <resources> tag:

   <resources>
       <string name="chat_button">Chat</string>
   </resources>

4. Save the files, then run a build to make sure you don't get any error messages.

   The app should display a vertically centered Chat button:

   

Adding an event listener for the Chat button

You'd like your app to start a chat when the user taps the Chat button. To do so, you'll need an event listener that detects the tap's click event, then starts the chat.

1. Switch to the MainActivity.java file in the Android Studio editor.

2. In the onCreate(Bundle) handler, and after the SDK initialization statement, declare a local Button variable and assign your layout button to it (highlighted):

   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
       Chat.INSTANCE.init(this, "4PBQNia9qItVDD98qmCYEfVesWLR4IFC");
       Button mChatButton;
       mChatButton = (Button) findViewById(R.id.chat_button);
   }

   The R.id.chat_button id is defined by the line android:id="@+id/chat_button" in the activity_main.xml layout file. The "@+id/" expression creates the id.

   Note that you must cast the View to Button before assigning it to your Button-typed variable.

3. The Button string is probably red, so click anywhere in the string and press Option+Enter (Mac) or Alt+Enter (Windows). Android Studio should add the following import statement to your file:

   import android.widget.Button;

4. Add the following click event listener after the variable assignment (highlighted):

   Button mChatButton;
   mChatButton = (Button) findViewById(R.id.chat_button);
   mChatButton.setOnClickListener(new View.OnClickListener() {
       @Override
       public void onClick(View v){
           // start chat
       }
   });

   The string View in View.OnClickListener() should turn red, indicating a missing import. Click anywhere in the red text and press Option+Enter (Mac) or Alt+Enter (Windows). Android Studio should add the following import statement to your file:

   import android.view.View;

5. Replace the // start chat comment in the onClick(View) method with the following statement:

   MessagingActivity.builder()
       .withEngines(ChatEngine.engine())
       .show(v.getContext());

   The MessagingActivity and ChatEngine objects should turn red. Click anywhere in each string, press Option+Enter (Mac) or Alt+Enter (Windows), and select Import Class if prompted. Android Studio should add the following import statements to your file:

   import zendesk.chat.ChatEngine;
   import zendesk.messaging.MessagingActivity;

   Note: from Messaging: 5.3.0, the dependency of zendesk.messaging.MessagingActivity has been updated to zendesk.classic.messaging.MessagingActivity.

That's it. The completed MainActivity subclass should look as follows:

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        Chat.INSTANCE.init(this, "4PBQNia9qItVDD98qmCYEfVesWLR4IFC");

        Button mChatButton;
        mChatButton = (Button) findViewById(R.id.chat_button);
        mChatButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v){
                MessagingActivity.builder()
                    .withEngines(ChatEngine.engine())
                    .show(v.getContext());
            }
        });
    }
}

You should have the following import statements at the top of the file:

package com.sample.mysamplechatapp;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;
import android.view.View;
import android.widget.Button;

import zendesk.chat.Chat;
import zendesk.chat.ChatEngine;
import zendesk.messaging.MessagingActivity;

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.

Testing that chat works

You can start a test chat if one or more chat agents are online. If nobody is online and you're a Zendesk Chat agent or administrator, you can chat with yourself by setting your status to Online in the Chat dashboard:

Build and run the application in your Android emulator. After tapping your custom Chat button, the chat interface should appear. Enter a message and tap right-arrow icon next to the message field to initiate the chat. Answer or skip the pre-chat questions.

Next steps

At this point you should have a working Android application that lets users chat with support agents. Use the sample application to experiment with the rest of the SDK. Here are some resources:

• Configuring the conversation
• Chat SDK Javadoc

Put your project under git and create branches to try out different things. You can always reset if something goes wrong.