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 Messaging SDK to incorporate Answer Bot with Chat and Support to create a unified messaging experience. However, because Answer Bot is available only as an add-on with the Zendesk Suite Professional plan or above, the Messaging SDK is not used in this tutorial.

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:

The tutorial uses version 3.2.0 of the Chat SDK. It was tested in version 4.2.1 of Android Studio.

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 comments section below or 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 16: Android 4.1 (Jelly Bean)
  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

  1. In your project files in the left sidebar, locate Gradle Scripts > build.gradle (Module: MySampleApp.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: MySampleApp).

  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 (in bold):

    dependencies {
      implementation group: 'com.zendesk', name: 'chat', version: '3.2.0'
      implementation group: 'com.zendesk', name: 'messaging', version: '5.1.0'  
      ...
    }

    The gradle.build file should look partially as follows:

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

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. Select Tools > AVD Manager.
  2. In the Your Virtual Devices screen, click Create Virtual Device.
  3. In the Select Hardware screen, select the Pixel 4 phone, and then click Next.
  4. In the System Image screen, click Download for the latest recommended system image (Android11 as 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 4 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:

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 (in bold):

    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 (in bold):

    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 (in bold):

    ...
    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;

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;

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:

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