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

Source: https://tamr.link/docs/how-it-works

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.

Who talks to whom:

```text
  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()`, or `destroy()` 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](https://tamr.link/docs/guides/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](https://tamr.link/docs/api).

## 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](https://tamr.link/docs/webhooks), which are the source of truth: an app can be closed when an order is cancelled, a server can't.
