# Tamr developer docs > Tamr's developer docs: the restaurant ordering and AI waiter SDK for the web, React Native, Flutter, iOS and Android, the HTTP API (/api/v1) and webhooks. Diners chat with the restaurant's AI waiter inside the restaurant's own app; the app's backend signs diner tokens, sends orders and receives signed webhooks. --- # Tamr developer docs > Put Tamr's AI waiter in your restaurant app with the restaurant ordering SDK for the web, React Native, Flutter, iOS and Android, plus the API reference and webhooks. Source: https://tamr.link/docs Tamr's SDK puts a restaurant's AI waiter inside its own app or website. Diners ask about the menu in their own language, get answers and dish cards, and order, either through Tamr or into your app's own cart. These docs cover the five SDKs, the HTTP API at `https://tamr.link/api/v1` and the webhooks Tamr sends your backend. - [Quickstart](https://tamr.link/docs/quickstart): Open the waiter in your app in five minutes, with a test key. - [SDKs](https://tamr.link/docs/sdks): Web, React Native, Flutter, iOS and Android. - [API reference](https://tamr.link/docs/api): Every route of the API, with curl, Node and Python. - [Webhooks](https://tamr.link/docs/webhooks): Signed events for orders, payments, bookings and chats. ## What you build The chat is a web page Tamr hosts, `https://tamr.link/w/{restaurant}`. The SDK shows that page in a webview (an iframe on a website) and passes messages between the page and your app. Everything the waiter decides happens in the page, so it improves without an app release. | Who | What it does | | --- | --- | | **Your app** | Shows the waiter with the SDK, says who the diner is by asking your backend for a short signed token, and, if the restaurant chose it, takes the waiter's dishes into its own cart. | | **Your backend** | Signs diner tokens. Receives webhooks. Optionally sends your orders, your product ids and your nutrition figures to Tamr, and erases a user on request. | | **Tamr** | Runs the waiter page, the AI, the menu, and, in one ordering mode, table orders, pickups and payments. | [How the SDK works](https://tamr.link/docs/how-it-works) explains the parts in more detail. ## Where orders go The restaurant chooses, with one setting in its Tamr dashboard ("Orders go to"): - **Tamr**, the default. The diner orders and pays inside the waiter page, as on Tamr's QR menu: dine-in at a table they scanned, or pickup. Your app hears that an order was placed or paid. - **The app's cart.** The waiter proposes dishes, your app puts them in its own cart, and your checkout takes the order. Your backend then sends the order to Tamr, so the waiter can offer "the usual" next time. Your code is mostly the same in both. [Ordering modes](https://tamr.link/docs/guides/ordering) covers the differences. ## Words used in these docs | Word | Meaning | | --- | --- | | Restaurant address | The restaurant's short name on Tamr, as in `tamr.link/w/{address}`. You pass it to the SDK as `restaurant`. | | Branch | One location of a chain. Each has an address too: lower-case letters, digits and dashes. | | App key | A publishable key, `tamr_pk_live_…` or `tamr_pk_test_…`. It names your app and is safe to ship in it. | | Secret API key | A key for your backend only, with permissions. Never ship it in an app or a website. | | Diner token | A short-lived JWT your backend signs to say which of your users is chatting. | | Launch code | A one-time code your backend asks Tamr for, for backends that can't sign tokens. | | External id | Your own id for a dish, size or option: your SKU or product id. | | Minor units | Money as a whole number in the currency's smallest unit, sent as a string: `"1250"` is 12.50 in USD. | ## For agents Every page is also served as Markdown: add `.md` to its address, or send `Accept: text/markdown`. [llms.txt](https://tamr.link/docs/llms.txt) lists them all and [llms-full.txt](https://tamr.link/docs/llms-full.txt) holds every page in one file. --- # 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 ` | 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. --- # Keys, test mode and guests > Publishable app keys and secret API keys for Tamr's SDK: test keys versus live keys, guest mode versus signed-in diners, and what the restaurant sets up for you. Source: https://tamr.link/docs/keys You need a publishable app key for your app and, for your backend, a secret API key. Build with a **test** app key and switch to a **live** one when you [go live](https://tamr.link/docs/guides/going-live). ## What the restaurant sets up for you Tamr switches the SDK on for the restaurant. Then an owner or admin of the restaurant's Tamr account works in **Settings** in the dashboard at `https://tamr.link/app`, or you do, if they invite you with the **Developer** role. A Developer sees every page below and nothing else in Settings: no menus, staff or billing. | Page | What it holds | | --- | --- | | **App keys** | Your publishable keys, test and live, each with its allowed website origins, its app ids (iOS bundle id, Android package name) and whether it allows guests. The diner token signing keys for each key. The webhook endpoints. A link to the host simulator. | | **API keys** | Secret API keys for your backend, each with its permissions. A Developer makes keys for the SDK only (diner sessions, catalog ids or orders) and sees only their own. | | **Install the SDK** | Setup per platform with the restaurant's address filled in, a **Try it** test key, the token signing samples, the methods and events with the version that added each, and **Copy setup for a developer**. It also shows which SDK versions your apps run and how fast the chat opens on real devices. | | **Waiter in your app** | How the waiter looks and talks in your app, and **Orders go to**. Changes are drafts until the restaurant publishes them. | | **External ids** | Your ids for each dish, size and option, by hand or as a CSV file. | **Ask the restaurant for** its address, the branch addresses if it has several, a test app key, its "Orders go to" choice, and a secret API key with the permissions you need. A key is shown once, when it is made, so whoever makes it should pass it to you safely. ## Test keys and live keys | | Test key `tamr_pk_test_…` | Live key `tamr_pk_live_…` | | --- | --- | --- | | Menu | The restaurant's own menus, against production | The same | | Label | The page shows "Test mode" | None | | Orders, payments, bookings | A pickup is a [test order](https://tamr.link/docs/guides/test-orders): checked and priced as a real one, never sent to the restaurant. Dine-in orders, payments and bookings are refused | Real | | Limits | 60 requests a minute per key (30 per network address), 50 conversations a day per key | 600 requests a minute per key (200 per network address) | | Dashboard | Kept out of Insights and billing, hidden from Conversations unless filtered | Counted | | Website origins | `https://…`, plus `http://localhost:` and `http://127.0.0.1:` | `https://…` only | | Webhooks | Sent to test endpoints, with `livemode: false` | Sent to live endpoints | The **Try it** step on Install the SDK can also make a two-hour test key for guests, filled into the code it shows. ## Guests or signed-in diners Each key either allows guests (**guest mode**) or not. - **Signed-in diner**, the default for live keys: your backend signs a token naming your user. The diner keeps the same conversation across their phones, gets "the usual" from their past orders, can save a nutrition goal and rate an order. - **Guest**: anyone can chat, with lower limits and no history or personalisation. Use it for apps with no login. A guest can still order and pay where the restaurant takes orders through Tamr. On a key without guest mode, an identity provider that answers "no one" leaves the chat unable to start. On a key with guest mode, it opens a guest chat. ## Secret API keys Your backend's key, made in **Settings > API keys** by an owner or admin, with only the permissions it needs (`diner:sdk`, `catalog:sdk`, `orders:sdk`, `catalog:read`). It never goes in an app or a website. See [Keys and permissions](https://tamr.link/docs/api#keys-and-permissions). ## The host simulator **Settings > App keys > Host simulator** opens the restaurant's waiter page as an app shows it, with its own two-hour test key. It can sign a test diner in, play the app's cart, and shows every message between the page and the app. Use it to see what your app will receive before you write code. --- # Quickstart: the AI waiter in your app in five minutes > Add Tamr's AI waiter to a web, React Native, Flutter, iOS or Android app in five minutes: get a test key, install the SDK, open the waiter, then sign diners in. Source: https://tamr.link/docs/quickstart Get a test key, install the SDK for your platform, and open the waiter. Pick your platform once in any tab below and every page of these docs follows it. ## 1. Get a test key In the restaurant's Tamr dashboard, **Settings > Install the SDK > Try it** makes a test key in guest mode that lasts two hours, so the waiter opens without a backend. Or ask the restaurant for a test key from **Settings > App keys**: a `tamr_pk_test_…` key, its restaurant address, and, on the web, your site's origin listed on the key (`http://localhost:` works for a test key). To work in the dashboard yourself, ask the restaurant to invite you with the **Developer** role. It opens Install the SDK, App keys, webhooks, External ids, Waiter in your app, the host simulator and API keys for the SDK, and nothing else: no menus, staff or billing. ## 2. Install the SDK Web: ```sh npm install @tamr/waiter-web ``` React Native: ```sh npx expo install @tamr/waiter-react-native react-native-webview expo-web-browser # Expo npm install @tamr/waiter-react-native react-native-webview # bare React Native ``` Flutter: ```sh flutter pub add tamr_waiter ``` iOS: ```swift .package(url: "https://github.com/abiroot/tamr-waiter-ios", from: "1.2.0"), // and in your target's dependencies: .product(name: "TamrWaiter", package: "tamr-waiter-ios"), ``` Android: ```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") } ``` Each platform has a little more setup (a CocoaPods install, the Android Gradle Plugin version, microphone permissions for voice notes). Its page in [SDKs](https://tamr.link/docs/sdks) lists it. ## 3. Open the waiter Replace `tamr_pk_test_…` with your key and `your-restaurant` with the restaurant's address. `myBackend.tamrToken()` stands for your own call to your backend, which signs a diner token; with a guest key you can return "no one" for now. Web: ```ts import { createWaiter } from "@tamr/waiter-web"; const waiter = createWaiter({ key: "tamr_pk_test_…", restaurant: "your-restaurant", mount: { kind: "launcher", position: "right" }, // or { kind: "sheet" }, or { kind: "inline", container } locale: "ar", // optional: branch, appearance, table, tableScan, mode, debug, onLog, title }); // Who the diner is, asked whenever the page needs a fresh token. Return null for "no one". waiter.setIdentityProvider(async (reason) => { const res = await fetch("/api/tamr-token"); // your backend signs it return res.ok ? { token: await res.text() } : null; }); // Orders go to your own cart ("Orders go to: the app's cart"): answer each line. waiter.onCartAdd(async ({ lines }) => ({ ok: true, lines: lines.map((l) => ({ lineId: l.lineId, ok: true })) })); // Everything the page tells you, typed. waiter.on("order.placed", (order) => console.log("order", order.orderId)); waiter.on("payment.completed", (payment) => console.log("paid", payment.paymentId)); waiter.open(); // also: close(), preload(), destroy() waiter.setLocale("fr"); // also: setAppearance, setText, setTheme, setContext, setStarters, setRestrictions, setGoal waiter.chat.send("What's good tonight?"); ``` React Native: ```tsx import { useEffect, useState } from "react"; import { Button } from "react-native"; import { SafeAreaProvider, useSafeAreaInsets } from "react-native-safe-area-context"; import { createWaiter, TamrWaiterHost, type Waiter } from "@tamr/waiter-react-native"; const waiter = createWaiter({ key: "tamr_pk_test_…", restaurant: "your-restaurant", locale: "ar", // optional: branch, appearance, table, tableScan, mode, launch, debug, onLog }); // Who the diner is, asked whenever the page needs a fresh token. Return null for "no one". waiter.setIdentityProvider(async () => { const token = await myBackend.tamrToken(); // your backend signs it return token ? { token } : null; }); // Orders go to your own cart ("Orders go to: the app's cart"): answer each line. waiter.onCartAdd(async (change) => ({ ok: true, lines: change.lines.map((line) => ({ lineId: line.lineId, ok: true })), })); // Everything the page tells you. waiter.on("payment.completed", (paid) => console.log("paid", paid.paymentId)); export function App() { return ( ); } function Root() { return ( <> ); } function MenuScreen() { useEffect(() => waiter.preload(), []); return