# Android SDK: the AI waiter in your Kotlin app

> Add Tamr's AI waiter to an Android app in Kotlin with link.tamr:waiter-android: Maven Central, Compose and Views, signed-in diners, cart lines, voice notes and debug mode.

Source: https://tamr.link/docs/sdks/android

`link.tamr:waiter-android` shows the waiter in an Android app, in a `WebView` that stays on Tamr's origin. `waiter-android-compose` adds a Compose bottom sheet, a full screen and a view; an app with only Views doesn't need it.

## Requirements

minSdk 26, compileSdk 35 or later, Android Gradle Plugin 8.6 or later, Kotlin 2.1 or later, and an up-to-date Android System WebView, one with `WEB_MESSAGE_LISTENER` (without it the waiter shows its retry state). The handlers are Kotlin `suspend` functions.

## Install

Both libraries are on Maven Central:

build.gradle.kts:

```kotlin
dependencies {
    implementation("link.tamr:waiter-android:1.2.0")
    // For the Compose sheet and full screen:
    implementation("link.tamr:waiter-android-compose:1.2.0")
}
```

List your app's package name on the app key. The SDK sends it; a key used from an app it doesn't list is logged, never refused.

## Open the waiter

Create one controller in the `ViewModel` of the screen where the waiter is likely to be opened, preload it each time that screen resumes, and show it on a tap:

```kotlin
class MenuViewModel(app: Application) : AndroidViewModel(app) {
    val waiter = TamrWaiterController(
        context = app,
        appKey = "tamr_pk_test_…",
        restaurant = "your-restaurant",
        locale = "ar",   // optional: branch, appearance, table, tableScan, mode, launch, host, debug, onLog
    ).apply {
        // Who the diner is, asked whenever the page needs a fresh token. Return null for "no one".
        setIdentityProvider { myBackend.tamrToken()?.let(TamrIdentity::token) }
        // Orders go to your own cart ("Orders go to: the app's cart"): answer each line.
        onCartAdd { change -> Reply(ok = true, lines = change.lines.map { LineAnswer(it.lineId, ok = true) }) }
        // Everything the page tells you.
        on("payment.completed") { (it as? PaymentCompletedMessage)?.let { paid -> log(paid.data.paymentId) } }
    }

    override fun onCleared() = waiter.dispose()
}

// In the Activity: model.waiter.preload() in onResume.

// Compose: the open state in rememberSaveable, so a rotation or process death keeps it.
var open by rememberSaveable { mutableStateOf(false) }
if (open) TamrWaiterSheet(model.waiter, onDismiss = { open = false })

// Views:
findViewById<TamrWaiterView>(R.id.waiter).attach(model.waiter)
```

- `TamrWaiterSheet(waiter, onDismiss)`: a Compose bottom sheet.
- `TamrWaiterScreen(waiter, onClose)`: a full screen that keeps clear of the system bars, the cutout and the keyboard. Create the controller with `appearance = Appearance(showBack = Patch.Set(true))` so the page shows its back arrow.
- `TamrWaiterView`: a View for a layout, an Activity or a dialog.

Call `dispose()` when the diner signs out (or in `onCleared`). After process death your app makes the controller again with the same settings; a signed-in diner comes back to the same conversation within the sitting.

Every method is for the main thread. The page follows `setTheme`, not the system's dark mode: pass your app's, in Compose from `isSystemInDarkTheme()`.

## Who the diner is

`setIdentityProvider` returns `TamrIdentity.token(…)`, `TamrIdentity.code(…)` or `null`, within 15 seconds. See [Diner identity](https://tamr.link/docs/guides/diner-identity).

## Voice notes

Optional: without them the waiter works by text. Declare the microphone in your app's manifest (the library declares only `INTERNET`):

AndroidManifest.xml:

```xml
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
```

Then answer `onMicrophonePermission` with Android's permission, asked with `ActivityResultContracts.RequestPermission()` for `RECORD_AUDIO`. The SDK never asks for the camera.

## Payments

With Tamr Pay on, the provider's page opens in a Custom Tab, never inside the WebView, and only when the link is `https`. When the diner closes it, your Activity resumes and the waiter checks the payment.

## Debug mode

`debug = true` writes every message both ways and the page's trace to `onLog` or `Log.d` (tag `TamrWaiter`), and makes the WebView inspectable in `chrome://inspect` in a debug build of your app. See [Debug mode](https://tamr.link/docs/guides/debugging).

## Methods

The page's messages are interfaces and the SDK's own kinds are value classes, not enums or sealed types, so a new one never breaks your `when`: keep an `else` branch.

| Method | What it does | Since |
| --- | --- | --- |
| `preload()` | Load the chat hidden, so it opens at once | 1.0.0 |
| `reload()`, `dispose()` | Load again after a failure; stop for good | 1.0.0 |
| `setIdentityProvider` | Who the diner is: TamrIdentity.token(…), TamrIdentity.code(…) or null | 1.0.0 |
| `onCartAdd`, `onCartUpdate`, `onCartRemove` | Answer the waiter's cart proposals, per line | 1.0.0 |
| `on(type)` | Everything the page tells your app | 1.0.0 |
| `setLocale`, `setAppearance`, `setText`, `setTheme`, `setContext`, `setStarters`, `setRestrictions` | Kept and sent again whenever the page loads again | 1.0.0 |
| `setGoal(goal)` | The diner's nutrition goal as your app keeps it | 1.1.0 |
| `sendCart`, `sendMessage`, `newChat`, `clearIdentity` | One-off messages, held until the chat is ready | 1.0.0 |
| `requestReview(orderId`, `dishes)` | After an order your backend sent: ask the diner to rate each dish | 1.1.0 |
