# Web SDK: the AI waiter on your website

> Add Tamr's AI waiter to a restaurant website with @tamr/waiter-web or one script tag: a launcher, a side sheet or inline, signed-in diners, cart lines and events.

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

`@tamr/waiter-web` puts the waiter on a restaurant's own website as a launcher bubble, a side sheet, or inline in an element you give it. The waiter is Tamr's hosted page in an iframe; the package mounts it and talks to it over a typed bridge.

## Requirements

Safari and iOS 16.4 or later, Chrome and Edge 111 or later, Firefox 114 or later, Samsung Internet 22 or later. That is what the waiter page in the frame is built for; the script itself runs on older browsers.

List your site's origins on the app key (`https://example.com`, `https://*.example.com`): the waiter frames only on a listed origin.

## Install

```sh
npm install @tamr/waiter-web
```

Or, with no build step, the script tag. `v1.js` is always the newest 1.x, cached for a minute; `https://tamr.link/sdk/web/1.2.1/waiter.js` is one version, never changed. The API is then on `window.TamrWaiter.createWaiter`.

```html
<script src="https://tamr.link/sdk/web/v1.js" async></script>
```

## Open the waiter

```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?");
```

`mount` decides where it shows: `{ kind: "launcher", position: "right" }`, `{ kind: "sheet" }`, or `{ kind: "inline", container }`. One waiter is one chat; two waiters on a page are two separate chats. Call `destroy()` when the diner signs out.

### The tag alone

With a key in guest mode, the tag alone adds an "Ask our AI waiter" button at the bottom right:

```html
<script src="https://tamr.link/sdk/web/v1.js"
  data-key="tamr_pk_test_…" data-restaurant="your-restaurant" async></script>
```

It has no identity provider, so a key that needs a diner token opens a chat that can't start. Optional attributes: `data-position="left"`, `data-label`, `data-color`, `data-locale`, `data-branch`, `data-debug="1"`.

## Who the diner is

`setIdentityProvider(fn)`: `fn(reason)` returns `{ token }`, `{ code }` or `null`, within 15 seconds. Your provider asks your backend for a fresh token every time; a token works once. See [Diner identity](https://tamr.link/docs/guides/diner-identity).

## Orders and the cart

When orders go to the app's cart, answer each proposed line with `onCartAdd`, `onCartUpdate` and `onCartRemove`, and tell the page what your cart holds with `sendCart`. When orders go to Tamr, listen for `order.placed` and `payment.completed`. See [Ordering modes](https://tamr.link/docs/guides/ordering) and [Events](https://tamr.link/docs/sdks/events).

## Payments

With Tamr Pay on, the waiter can offer to take the bill. The provider's page always opens in a new tab, never inside the frame. If the browser blocks the tab, the chat shows the link instead.

## Content Security Policy

If your site sends one, allow Tamr's origin:

```text
script-src  https://tamr.link    (only for the script tag; or its nonce)
frame-src   https://tamr.link
```

No `unsafe-inline` or `unsafe-eval` is needed: styles are constructed stylesheets in a shadow root. For Safari before 16.4, pass your page's nonce (the `nonce` option, or the tag's own `nonce`). A `Permissions-Policy: microphone=()` turns voice notes off; set `microphone: false` to not ask at all.

## Debug mode

`debug: true`, or `data-debug="1"` on the tag, prints every message both ways and the page's own trace, as `[tamr] page <level>: …` and `[tamr] shell: …`, to `onLog` or the console. Tokens, codes and what the diner types are never logged. See [Debug mode](https://tamr.link/docs/guides/debugging).

## Methods

| Method | What it does | Since |
| --- | --- | --- |
| `open()`, `close()` | Show or hide the launcher's panel or the sheet | 1.0.0 |
| `preload()` | Load the chat hidden, so it opens at once | 1.0.0 |
| `setIdentityProvider(fn)` | Who the diner is: a token, a launch code or no one | 1.0.0 |
| `onCartAdd`, `onCartUpdate`, `onCartRemove` | Answer the waiter's cart proposals, per line | 1.0.0 |
| `on(type`, `listener)` | Everything the page tells your site, typed | 1.0.0 |
| `setLocale`, `setAppearance`, `setText`, `setTheme`, `setContext`, `setStarters`, `setRestrictions` | Kept and sent again whenever the page reloads | 1.0.0 |
| `setGoal(goal)` | The diner's nutrition goal as your app keeps it | 1.1.0 |
| `sendCart(lines)`, `chat.send(text)`, `chat.new()`, `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 |

## The older widget.js

`tamr.link/widget.js`, with one `data-restaurant` attribute, keeps working unchanged. It opens the restaurant's QR menu chat, with no app key and no bridge. New sites should use this package.
