# Build your own chat UI

> Draw a native AI waiter chat on Tamr's Client API: start a session, stream the waiter's replies as server-sent events, draw dish cards, and renew expired sessions.

Source: https://tamr.link/docs/guides/custom-chat

Most apps use an SDK and never call the Client API. Use it if you want a native chat screen of your own. The waiter page itself uses only these routes, so anything it does, your client can do.

## 1. Start a session

[Start a session](https://tamr.link/docs/api/start-session) with your app key and one of: a diner `token`, a launch `code`, or, on a key in guest mode, the device's `device` id. Use a random id of 22 or more base64url characters (128 bits) and keep it on the device: a guest is told apart by it, and with one that long the guest's open pickups and their payment come back after the app restarts.

The session comes back in the `x-tamr-session` response header, never in the body. It slides 12 hours from its last use, up to 7 days.

## 2. Send the session on every call

Send `x-tamr-key` and `x-tamr-session` on every call, and `x-tamr-device` for a guest. When a call answers 401 `session_expired`, start a new session with a fresh token or code, then retry the call once. If several calls hit `session_expired` at once, share one renewal. When the diner logs out, call [End a session](https://tamr.link/docs/api/end-session).

## 3. Chat

[Send a message](https://tamr.link/docs/api/chat) with `{ "message": "…" }`, up to 2,000 characters. The reply streams as server-sent events:

- `message` events carry `start` (the conversation and message ids), `text` (a `delta` to append) or `card` (a card to draw, with everything it shows: a dish's name, price, image, allergens and figures);
- then `done`, with how the turn ended, or `error`.

Card kinds today: `dishes`, `surprise_basket`, `quick_replies`, `dietary_filters`, `language_choice`, `staff_called`, `branch_info`, `booking_times`, `booking`, `saved`, `cart_proposal`, `order_offer`, `pay_offer` and `build`. New kinds arrive within v1: skip what you don't know and keep showing the text.

**Draw only what a card says.** Never work out a total, a nutrition figure or a fit yourself: the waiter checks those in code and the card carries the answer.

## The rest of the Client API

| What | Routes |
| --- | --- |
| The waiter and the menu | [Get the waiter](https://tamr.link/docs/api/get-waiter), [Get the menu](https://tamr.link/docs/api/get-menu), [Warm up the waiter](https://tamr.link/docs/api/warm-up) |
| Conversations | [List](https://tamr.link/docs/api/list-conversations), [get](https://tamr.link/docs/api/get-conversation) and [close](https://tamr.link/docs/api/close-conversation) them |
| Voice notes | [Transcribe a voice note](https://tamr.link/docs/api/transcribe) |
| Your cart | [Match your cart](https://tamr.link/docs/api/match-cart) |
| The diner | [Their usual](https://tamr.link/docs/api/get-usual), [their nutrition goal](https://tamr.link/docs/api/get-goal), [post-meal reviews](https://tamr.link/docs/api/match-review) |
| Orders through Tamr | [Seat at a table](https://tamr.link/docs/api/seat-at-table), [send a table order](https://tamr.link/docs/api/send-table-order), [pickups](https://tamr.link/docs/api/place-pickup), [Tamr Pay](https://tamr.link/docs/api/start-payment) |

A browser may call the Client API only from an origin listed on the key. No Server API route answers a browser at all.

## The client library

`@tamr/api` is a typed client for all of this, generated from the spec: `startSession`, one function per route, the chat as an async iterator, and `onSessionExpired` for renewal. Its examples include a minimal custom chat in the browser. Install it with `npm install @tamr/api`; see [the client library](https://tamr.link/docs/api#the-client-library).
