> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Getting started

> **Warning**
>
> Ada has deprecated Chat. Messaging fully replaces Chat on December 15, 2026. Read [Introducing Messaging](https://docs.ada.cx/2026-09-30-introducing-messaging) to learn how to migrate.

This page covers the legacy Chat Android SDK. Follow the [Messaging Android upgrade guide](/messaging/android/getting-started#upgrade-from-the-existing-android-sdk) to migrate.

This guide will help you set up the Ada Android SDK in your app. The process involves two main steps:

1. [Install](#install-android-sdk) the SDK: Add the SDK manually to your project.
2. [Launch](#launch-ada) Ada: Choose one of the available options to display Ada, such as [XML](#xml), [programmatic setup](#programmatically), [dialog](#dialog), or [activity](#activity).

Follow the instructions below to install the SDK and start integrating Ada into your app!

### Install Android SDK

1. Get the Android SDK `.aar` file [here](https://mvnrepository.com/artifact/io.github.adasupport).

   To download the AAR file:

   * Click on the package you need (e.g., `android-sdk`, `android-sdk-appcompat`, or `android-sdk-appcompat-legacy`)
   * Select your desired version from the versions list
   * In the Files section, click on the `.aar` file to download it
2. To install the library, save the `.aar` file under your app module libs folder (for example "MyAwesomeProject/app/libs"), and include `*.aar` in the application-level `build.gradle` file.

**`build.gradle`**

```java build.gradle
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}
```

3. Synchronize the project.

You can also import an `.aar` file using Android Studio. First, download the versioned `.aar`, and then simply define the implementation for the new local library module.

**`build.gradle`**

```java build.gradle
implementation files("/path/to/android-sdk-<version_number>.aar")
```

Note that if the `android-sdk-appcompat-<version_number>.aar` or the `android-sdk-appcompat-legacy-<version_number>.aar` is used, then the dependency declaration must resemble the following, with the `appcompat` libraries depending on the `android-sdk` library.

**`build.gradle`**

```java build.gradle
implementation files("/path/to/android-sdk-<version_number>.aar")
implementation files("/path/to/android-sdk-appcompat-<version_number>.aar")
```

### Install via Maven Central

Alternatively, you can install the Ada Android SDK directly from Maven Central Repository. Add the following dependency to your app-level `build.gradle` file:

#### Standard SDK

**`build.gradle`**

```java build.gradle
dependencies {
    implementation "io.github.adasupport:android-sdk:<version>"
    implementation "io.github.adasupport:android-sdk-appcompat:<version>"
}
```

#### Legacy SDK

For projects that require the legacy version:

**`build.gradle`**

```java build.gradle
dependencies {
    implementation "io.github.adasupport:android-sdk:<version>"
    implementation "io.github.adasupport:android-sdk-appcompat-legacy:<version>"
}
```

Replace `<version>` with the latest version number available on [Maven Central](https://central.sonatype.com/namespace/io.github.adasupport).

> **Note**
>
> Make sure your project's `build.gradle` file includes `mavenCentral()` in the repositories block:
>
> ```java build.gradle
> repositories {
>     mavenCentral()
>     // other repositories...
> }
> ```

After adding the dependency, synchronize your project to download and integrate the SDK.

## Launch Ada

### XML

The simplest way to start Ada chat is via XML, as in the following example. You must replace `my-bot` with the actual name of your bot, and modify any other relevant as needed.

**`XML`**

```xml XML
<!-- XML -->
<support.ada.embed.widget.AdaEmbedView
        android:id="@+id/ada_chat_frame"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:ada_handle="my-bot" />
```

To display the view, the `ada_handle` parameter is required. If you specify it as an attribute, the chat is displayed immediately upon attachment to the parent view. If it is not specified, then you can do it later programmatically, using the method `initialize(settings: AdaEmbedView.Settings)`.

**`Kotlin`**

```kotlin Kotlin
// Delayed initialization
val adaView = findViewById(R.id.ada_chat_frame)

adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .build()
adaView.initialize(adaSettings)
```

### Programmatically

To programmatically create the chat frame, create a view object and pass context to the constructor.

**`Kotlin`**

```kotlin Kotlin
val adaView = AdaEmbedView(getContext())

val adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .build()
adaView.initialize(adaSettings)
```

After this, the view will be created, but will not be initialized. To do this, call `initialize(settings: AdaEmbedView.Settings)`, passing the settings object as an argument.

Finally, to display the newly created chat frame on screen, simply add the view to your container.

### Dialog

To display a separate chat window on top of the current window, you can use `AdaEmbedDialog`.

First, create a dialog object and pass the settings to its arguments using a constant, `AdaEmbedDialog.ARGUMENT_SETTINGS`.

**`Kotlin`**

```kotlin Kotlin
val dialog = AdaEmbedDialog()
 adaDialog.arguments = Bundle().apply {
    putParcelable(AdaEmbedDialog.ARGUMENT_SETTINGS, settings)
 }
```

Then show it using the native Android `show` method.

**`Kotlin`**

```kotlin Kotlin
dialog.show(supportFragmentManager, AdaEmbedDialog.TAG)
```

> **Note**
>
> TAG is a simple class name, you can use any value you want.

### Activity

Use `AdaEmbedActivity` to open the chat in a separate window attached to the app navigation.

To do this, create an `Intent`, and put the settings in it with the key `AdaEmbedActivity.EXTRA_SETTINGS`, then run the activity.

**`Kotlin`**

```kotlin Kotlin
val intent = Intent(context, AdaEmbedActivity::class.java)
intent.putExtra(AdaEmbedActivity.EXTRA_SETTINGS, settings)
context.startActivity(intent)
```

> **Note**
>
> You can use "AdaEmbedActivity" as a regular Android activity. For example, flags and actions can be added.

## File Upload Support

If your implementation uses Zendesk live agent support, file uploads might require a few additional steps, based on your chosen method for launching the SDK.

`AdaEmbedActivity` and `AdaEmbedDialog` already have this functionality, but if you work directly with `AdaEmbedView` you must handle uploads as described below.

1. Set up a callback to `AdaEmbedView`. This callback will be fired when a user makes a request to attach a file.
2. Once you get the URI, invoke `filePickerCallback.onFileTaken(someUri)`. This will signal to `AdaEmbedView` that the file is ready to attach. It's also possible to pass `null`, which will cancel the request.

**`Kotlin`**

```kotlin Kotlin
adaView.filePickerCallback = { filePickerCallback ->
    filePickerCallback.onFileTaken(someUri)
    true
}
```

This operation doesn't require you to pass the file URI to callback immediately. You can save `filePickerCallback` and invoke the callback later (for example, taking the URI via file picker).

To notify `AdaEmbedView` that you are going to handle file attachments, you should return `true`.