Getting Started

Add Messaging to your project to engage with your users from your Android app.

Prerequisites

Before starting the integration of the Zendesk SDK, please ensure that the following prerequisites are fulfilled.

Ensure you meet the minimum supported Android API level

  • Minimum API level (minSdkVersion) for the Zendesk SDK is 21.
  • Minimum Java version required to run the Zendesk SDK is 8. Below is an example of how to configure your project to compile with Java version 8, using the following compile options added to your build.gradle module:

    android {    compileOptions {        sourceCompatibility = JavaVersion.VERSION_1_8        targetCompatibility = JavaVersion.VERSION_1_8    }}

Obtain a channel key from Zendesk's Admin Center

Before you initialize your SDK, you'll need to obtain a channel key. The channel key is a unique identifier that the SDK requires to initialize correctly. You can obtain it from the Zendesk Admin Center. For instructions, see Working with messaging in the Zendesk SDKs for Android and iOS. If you're not a Zendesk admin on your account, ask one to get it for you.

Add the SDK dependencies

You can add the Android SDK to your project using Maven.

The following permissions are automatically added to your AndroidManifest because the SDK has to make network requests to work as expected.

<uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  1. Add the Zendesk Maven repository to your project dependency.

    repositories {    maven {        url "https://zendesk.jfrog.io/artifactory/repo"    }}
  2. Add the following dependency to your app's build.gradle:

    implementation "zendesk.messaging:messaging-android:1.0.0"

Obtain the channel key

Before you initialize your SDK, you'll need to obtain a channel key. The channel key is a unique identifier that the SDK requires to initialize correctly. You can obtain it from the Zendesk Admin Center. For instructions, see Working with messaging in the Zendesk SDKs for Android and iOS. If you're not a Zendesk admin on your account, ask one to get it for you.

Initialize the SDK

Initialize the SDK in the onCreate method of your Application class. To do this, you'll need your channel key, which you can find in the Zendesk Admin Center. If you don't have admin access to Zendesk, ask a Zendesk admin to get the information for you.

The snippets below give an example of a Messaging initialization in both Kotlin and Java.

Kotlin

import android.app.Applicationimport android.util.Logimport zendesk.messaging.android.Messaging
/** * A sample [Application] with a [Messaging] integration in Kotlin. */class IntegrationApplication : Application() {
    override fun onCreate() {        super.onCreate()
        Messaging.initialize(            context = this,            channelKey = "{channel_key}",            successCallback = {                Log.i("IntegrationApplication", "Initialization successful")            },            failureCallback = { cause ->                Log.e("IntegrationApplication", "Initialization failed", cause)            }        )    }}

Java

import android.app.Application;import android.util.Log;import zendesk.messaging.android.FailureCallback;import zendesk.messaging.android.Messaging;import zendesk.messaging.android.MessagingError;import zendesk.messaging.android.SuccessCallback;
/** A sample {@link Application} with a {@link Messaging} integration in Java. */class JavaIntegrationApplication extends Application {
    @Override    public void onCreate() {        super.onCreate();
        Messaging.initialize(                this,                "{channel_key}",                new SuccessCallback<Messaging>() {                    @Override                    public void onSuccess(Messaging value) {                        Log.i("IntegrationApplication", "Initialization successful");                    }                },                new FailureCallback<MessagingError>() {                    @Override                    public void onFailure(@Nullable MessagingError cause) {                        Log.e("IntegrationApplication", "Messaging failed to initialize", cause);                    }                });    }}

Show the conversation

If Messaging.initialize() is successful, you can use the code snippets below anywhere in your app to show the conversation screen.

If Messaging.initialize() is not successful, a stub implementation of the Messaging class is returned that logs to the console.

Kotlin

Messaging.instance().showMessaging(context)

Java

Messaging.instance().showMessaging(context);

Next Steps

If you have completed the steps above, you are now in good shape to explore the SDK and understand how messaging will work for your business and your end users.

 Push Notifications

To ensure a good end-user experience, we also recommend setting up push notifications to work correctly with your app. The steps required to set it up are outlined in Push notifications.

 Advanced Integration

To explore more advanced integration options, see Advanced integration.

Troubleshooting

Logging

Logging is disabled by default. You can enable it by using the following in either Java or Kotlin:

import zendesk.logger.Logger;
Logger.setLoggable(true);

You can check the state of the Logger by using:

Logger.isLoggable();