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:

  • 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

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.