Getting Started

Getting Started

Follow these steps to integrate the Talk SDK in your app:

1. Register your app in Zendesk Support
2. Add a Talk digital line
3. Add the SDK dependencies to your app
4. Initialize the SDK
5. Set an anonymous identity
6. Create an instance of the SDK
7. Check for agent availability
8. Make a call

The code snippets on this page show a simple, light-touch integration using the built-in UI that comes with the SDK. You can decide to use the API and build your own UI if you want, or customize the look of the built-in UI. For more details, see Using the SDK with your own UI or Customizing the look.

Prerequisites

In addition to a Zendesk Talk subscription, the SDK has the following requirements:

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

Registering your app in Zendesk Support

Ask a Zendesk admin on your customer support team to do the following:

• Register your application in Zendesk Support. Tell the admin to make sure to select Anonymous for the Authentication method. The SDK only supports Anonymous authentication
• Provide you with the App ID and Client ID created when they registered the app

Refer the admin to Registering the mobile app in Zendesk Support in Support help.

The App ID and Client ID are required for initializing the SDK.

Adding a Talk digital line

Ask a Zendesk admin on your customer support team to do the following:

• Add a Talk digital line if one doesn't exist yet
• Provide you with the digital line's nickname

Refer the admin to Adding a Talk digital line in Talk help.

Adding the SDK dependencies

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. In the dependencies section, add following dependency:

   dependencies {
       implementation("zendesk.talk:talk-android:1.2.1")
       ...
   }

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

Initializing the SDK

You should initialize the Talk SDK in the onCreate method of your Application subclass, or in an Activity when your application is launched.

You'll need the App ID, Client ID, and digital line nickname you obtained in the previous steps.

Java

Zendesk.INSTANCE.init(
    this,
    "yourzendeskurl",
    "appID",
    "clientID"
);

Kotlin

Zendesk.INSTANCE.init(
    this,
    "yourzendeskurl",
    "appID",
    "clientID"
)

Setting an anonymous identity

To set an anonymous identity, add the following statement before any interaction with the SDK. We recommend putting it after Zendesk.INSTANCE.init(...).

Java

Identity identity = new AnonymousIdentity.Builder()
                    .withEmailIdentifier("optional user email")
                    .withNameIdentifier("optional user name")
                    .build();
Zendesk.INSTANCE.setIdentity(new AnonymousIdentity());

Kotlin

val identity = AnonymousIdentity.Builder()
            .withEmailIdentifier("optional user email")
            .withNameIdentifier("optional user name")
            .build()
 Zendesk.INSTANCE.setIdentity(identity)

See How anonymous identities work in the mobile SDKs for more information about the lifecycle of an anonymous identity.

Setting the user email and name will improve the user experience of your customer by providing user context to your agent.

Note: Unlike other Zendesk SDKs, JWT authentication is not supported in the Talk SDK. Attempting to use JWT authentication will result in failures.

Note: Zendesk Talk relies on the Zendesk Support SDK to get the access token to allow calls. Zendesk Support requires an identity to produce the access token, but the Talk SDK does not use that identity to identify the caller.

Creating an SDK instance

To use the SDK's API, you need to create an instance of the SDK first. Create the instance after the SDK is initialized and the anonymous identity is set.

Java

Talk talk = Talk.create(Zendesk.INSTANCE);

Kotlin

val talk = Talk.create(Zendesk.INSTANCE)

We recommend keeping the Talk instance a singleton in your application.

Note: If Zendesk.INSTANCE is not initialized before calling Talk.create, an IllegalStateException is thrown.

Checking for agent availability

Use the lineStatus method to determine if any agents are available for a Talk digital line. We recommend hiding the call button when no agents are available to improve the user experience.

The lineStatus method takes a digital line nickname and returns a LineStatusResult, which is a Kotlin sealed class that can contain the following states:

• LineStatusResult.Success - The line status check was successful. Contains two properties:

  Name	Type	Description
  agentAvailable	boolean	true when the digital line is ready to be used and at least one agent is available for the line; false otherwise
  recordingConsent	RecordingConsent	Describes options for the user to opt in or opt out of the call recording. The value is null if the end user can't change the options. In this version of the SDK, the property is always null

• LineStatusResult.Failure.DigitalLineNotFound - The digital line nickname does not exist in the account.

• LineStatusResult.Failure.Unknown - The line status check failed due to any reason.

Example:

Java

TalkListenableFuture<LineStatusResult> job = TalkJavaCompat.lineStatus(talk, "your digital line nickname");
job.addListener(new TalkJavaCompatListener<LineStatusResult>() {
    @Override
    public void onSuccess(@NonNull LineStatusResult result) {
        if(result instanceof LineStatusResult.Success) {
            LineStatusResult.Success success = (LineStatusResult.Success) result;
            if(success.getAgentAvailable()) {
                phoneIcon.setVisibility(View.VISIBLE);
            } else {
                phoneIcon.setVisibility(View.GONE);
            }
        } else {
            phoneIcon.setVisibility(View.GONE);
        }
    }

    @Override
    public void onError(@NonNull Throwable throwable) {
        // error occurred when executing lineStatus
    }
});

Note The Java examples show the simplest way of using the SDK public API. For more advanced usage, see Using TalkJavaCompat.

Kotlin

yourCoroutineScope.launch {
    when (talk.lineStatus("your digital line nickname")) {
        is LineStatusResult.Success -> phoneIcon.visibility = View.VISIBLE
        is LineStatusResult.Failure -> phoneIcon.visibility = View.GONE
    }
}

Making a call

After determining that agents are available, you can initialize a call.

The SDK provides a built-in UI for checking the required permissions and calling an agent. You can run it with the following statement:

Java

talk.startCallSetupFlow(this, "your digital line nickname", null);

Kotlin

talk.startCallSetupFlow(context = this, digitalLine = "your digital line nickname", successIntent = null)

To customize the look of the built-in permission or call screen, see Customizing the look.

If prefer to build and use your own permission or call screen UIs, see Using the SDK with your own UI.