Send a message

Send the diner's message to the AI waiter and stream the reply as server-sent events: text, dish cards and the turn's end.

POST/api/v1/chatClient API

One diner message, up to 2,000 characters. The reply streams as server-sent events: message events carry start, text (a delta to append) or card (everything the card shows), then done. New event types and card 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. See Build your own chat.

Authentication

Client API. Send your publishable key in x-tamr-key and the diner's session in x-tamr-session, from Start a session. For a guest's session, also send its device id in x-tamr-device. A browser may call it only from an origin listed on the key.

Headers

NameTypeRequiredDescription
x-tamr-devicestringNoGuest sessions only: the device id the session was exchanged with. Matches ^[A-Za-z0-9_-]{8,128}$.
x-tamr-appstringNoNative apps only: the app's iOS bundle id or Android package name. A key used from an app it doesn't list is logged, never refused. Matches ^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$.

Request body

A ChatRequest.

FieldTypeRequiredDescription
messagestringYes1 to 2,000 characters.
conversationIdstringNo1 to 200 characters.
branchstringNoAn address: lower-case letters, digits and dashes.
modestringNoOne of dine_in, pickup, delivery.
tablestringNo1 to 40 characters.
localestringNoA language tag, such as ar or en-GB.
restrictionsobjectNo
restrictions.avoidAllergensarray of stringYesAt most 10 items. Each: One of gluten, dairy, egg, nuts, sesame, soy, fish, shellfish, peanut, mustard.
restrictions.keepDietsarray of stringYesAt most 8 items. Each: One of vegan, vegetarian, gluten_free, halal, kosher, dairy_free, nut_free, keto.
cartarray of objectNoAt most 50 items.
cart[].dishIdstringYes1 to 200 characters.
cart[].variantIdstringNo1 to 200 characters.
cart[].optionIdsarray of stringNoAt most 20 items. 1 to 200 characters.
cart[].quantityintegerYes1 to 99.
cart[].picksarray of objectNoAt most 120 items.
cart[].picks[].pickIdstringYes1 to 200 characters.
cart[].picks[].countintegerYes1 to 20.
goalobjectNo
goal.modestringYesOne of cutting, maintain, bulking.
goal.kcalintegerNoCalories for one meal: a ceiling when cutting or maintaining, a floor when bulking. 100 to 3,000.
goal.proteinGramsintegerNoGrams of protein for one meal, always a floor. 5 to 300.
takesarray of stringNoAt most 16 items. Matches ^[a-z][a-z_.]{0,47}$.
hideobjectNo
hide.retailSuggestionsbooleanNo
hide.loyaltybooleanNo
cardActionsarray of objectNoAt most 6 items.
cardActions[].tool"offer_to_order"Yes
cardActions[].offeredAtstringYesAt most 40 characters.
cardActions[].outcome"added"Yes
cardActions[].linesarray of objectYes1 to 8 items.
cardActions[].lines[].dishIdstringYes1 to 200 characters.
cardActions[].lines[].quantityintegerYes1 to 99.
cardActions[].lines[].sizestring or nullNoAt most 80 characters.

Response

The reply streams as server-sent events (text/event-stream), each an event: line and a data: line of JSON.

EventdataWhat it says
messageChatEventA start (the conversation and message ids), a text (a delta to append) or a card (a card to draw).
doneChatDoneHow the turn ended.
erroranyThe turn failed after it started.

Example

curl -N https://tamr.link/api/v1/chat \
  -H "x-tamr-key: $TAMR_APP_KEY" \
  -H "x-tamr-session: $TAMR_SESSION" \
  -H "content-type: application/json" \
  -d '{
  "message": "Something light without dairy?"
}'

Example response

text/event-stream
event: message
data: {"type":"start","conversationId":"cmconv0001","messageId":"msg_01"}

event: message
data: {"type":"text","delta":"Try the grilled halloumi"}

event: message
data: {"type":"card","cardId":"call_01","card":{"kind":"dishes","layout":"carousel","framing":"Two light ones","dishes":[{"dishId":"cmdish0001","name":"Grilled halloumi","price":"1200","currency":"USD","imageUrl":"https://tamr.link/image-proxy/media/halloumi.webp","calories":420,"proteinGrams":24,"carbsGrams":8,"fatGrams":31,"allergens":["dairy"],"dietaryTags":["vegetarian"],"available":true,"externalId":"SKU-HALLOUMI"},{"dishId":"cmdish0002","name":"Mint lemonade","price":"400","currency":"USD","imageUrl":null,"calories":null,"proteinGrams":null,"carbsGrams":null,"fatGrams":null,"allergens":[],"dietaryTags":["vegan","a-tag-from-later"],"available":true,"externalId":null}]}}

event: done
data: {"finishReason":"stop"}

Errors

Every error has the same body; switch on data.code. See Errors and rate limits.

data.codeStatusWhat to do
app_key_invalid401The key is wrong, revoked or of another kind. Check it in the dashboard.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.
origin_not_allowed403A browser called from an origin the key doesn't list. Add the origin to the key.
session_expired401Start a new session with a fresh token or code, then send the call again once.
invalid_request400A field doesn't match the spec. The message says which.
rate_limited429Wait retryAfter seconds (also in the Retry-After header), then try again.
message_rejected422The message was refused (too long, or not about the restaurant). Show the message.
menu_unavailable404No published menu is served at that branch and service mode.
not_found404Not this diner's, or doesn't exist. The two read the same on purpose.
test_limit_reached429A test key's 50 conversations for the day are spent. Try again tomorrow, or use a live key.
max_turns_reached429The conversation is as long as it may be. Start a new one.
after_hours_closed503The location takes no conversations now. Show the message: the restaurant may have written it.
waiter_resting503The restaurant has paused its waiter. Show the message.
unavailable503Tamr can't serve this now. Try again later.