How the Tamr SDK works
How Tamr's AI waiter SDK works: a hosted waiter page in a webview, a typed bridge to your app, diner identity from your backend, and the Client and Server APIs.
The SDK is a thin shell. It shows Tamr's hosted waiter page in a webview, passes typed messages between that page and your app, and opens payment pages outside the webview. The page does the rest: the chat, the AI, cards, renewing the diner's session, retries, and what goes in a cart. A fix to the waiter reaches every app without an app release.
Diner's phone Your servers
+--------------------------------+ +------------------------------+
| Your app | "give me a | Your backend |
| login, menu, cart, checkout | diner token" | signs diner tokens |
| | --------------> | sends orders and ids |
| +--------------------------+ | | receives webhooks |
| | Tamr SDK (webview) | | +------------------------------+
| | the waiter page | | | ^
| | tamr.link/w/{restaurant}| | Server API | | webhooks
| +--------------------------+ | v |
+--------------|-----------------+ +------------------------------+
| Client API | Tamr |
+---------------------------------> | https://tamr.link/api/v1 |
+------------------------------+The controller
Every SDK has one object for one chat: createWaiter on the web and in React Native, TamrWaiterController in Flutter, Swift and Kotlin.
- One controller is one chat, shown in one place at a time. Two controllers are two separate chats.
- Create it where the waiter is likely to open, such as the menu screen rather than app start, and call
preload()there. A preloaded chat opens at once. Each preload starts a session, so don't preload on every screen. - A hidden chat is released after 10 minutes, and under memory pressure. It loads again on the next open or preload.
- When the diner signs out, call
clearIdentity()and dispose of the controller (dispose(), ordestroy()on the web). Make a new one for the next diner. - Keep the controller alive while the chat is shown. If the app dies, make it again with the same settings: a signed-in diner comes back to the same conversation within the sitting (3 hours), unless they started a new chat or logged out.
Who the diner is
You give the controller an identity provider: a function the page calls whenever it needs a fresh diner token, with a reason (first_open, expired or refused). It answers within 15 seconds with a token your backend signed, a launch code, or "no one". The page handles renewal, retries and expiry itself, and a signed-in chat never starts as a guest and switches later. See Diner identity.
The two APIs
| Client API | Server API | |
|---|---|---|
| Who calls it | The waiter page, or your app if it draws its own chat | Your backend |
| Credentials | The app key in x-tamr-key and the diner's session in x-tamr-session | A secret API key: Authorization: Bearer <key> |
The waiter page uses only the Client API, so anything it does, a client of your own can do. See the API reference.
Events and webhooks
The SDK tells your app what happens in the chat (order.placed, checkout, waiter.called and more) so it can update its screen. Your backend hears the same facts as signed webhooks, which are the source of truth: an app can be closed when an order is cancelled, a server can't.