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.

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
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:

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.

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

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.

MethodWhat it doesSince
preload()Load the chat hidden, so it opens at once1.0.0
reload(), dispose()Load again after a failure; stop for good1.0.0
setIdentityProviderWho the diner is: TamrIdentity.token(…), TamrIdentity.code(…) or null1.0.0
onCartAdd, onCartUpdate, onCartRemoveAnswer the waiter's cart proposals, per line1.0.0
on(type)Everything the page tells your app1.0.0
setLocale, setAppearance, setText, setTheme, setContext, setStarters, setRestrictionsKept and sent again whenever the page loads again1.0.0
setGoal(goal)The diner's nutrition goal as your app keeps it1.1.0
sendCart, sendMessage, newChat, clearIdentityOne-off messages, held until the chat is ready1.0.0
requestReview(orderId, dishes)After an order your backend sent: ask the diner to rate each dish1.1.0