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.
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 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.
3. Chat
Send a message with { "message": "…" }, up to 2,000 characters. The reply streams as server-sent events:
messageevents carrystart(the conversation and message ids),text(adeltato append) orcard(a card to draw, with everything it shows: a dish's name, price, image, allergens and figures);- then
done, with how the turn ended, orerror.
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, Get the menu, Warm up the waiter |
| Conversations | List, get and close them |
| Voice notes | Transcribe a voice note |
| Your cart | Match your cart |
| The diner | Their usual, their nutrition goal, post-meal reviews |
| Orders through Tamr | Seat at a table, send a table order, pickups, Tamr Pay |
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.