Schemas

The named schemas of Tamr's API: chat requests and events, dish cards, the menu, conversations, errors and every webhook payload, field by field.

The objects the API reference pages link to, field by field, from the committed OpenAPI spec. Nested objects show two levels deep; the spec at tamr.link/api/v1/openapi.json has every level.

ChatRequest

FieldTypeDescription
messagestring1 to 2,000 characters.
conversationIdstringMay be absent. 1 to 200 characters.
branchstringMay be absent. An address: lower-case letters, digits and dashes.
modestringMay be absent. One of dine_in, pickup, delivery.
tablestringMay be absent. 1 to 40 characters.
localestringMay be absent. A language tag, such as ar or en-GB.
restrictionsobjectMay be absent.
restrictions.avoidAllergensarray of stringAt most 10 items. Each: One of gluten, dairy, egg, nuts, sesame, soy, fish, shellfish, peanut, mustard.
restrictions.keepDietsarray of stringAt most 8 items. Each: One of vegan, vegetarian, gluten_free, halal, kosher, dairy_free, nut_free, keto.
cartarray of objectMay be absent. At most 50 items.
cart[].dishIdstring1 to 200 characters.
cart[].variantIdstringMay be absent. 1 to 200 characters.
cart[].optionIdsarray of stringMay be absent. At most 20 items. 1 to 200 characters.
cart[].quantityinteger1 to 99.
cart[].picksarray of objectMay be absent. At most 120 items.
goalobjectMay be absent.
goal.modestringOne of cutting, maintain, bulking.
goal.kcalintegerMay be absent. Calories for one meal: a ceiling when cutting or maintaining, a floor when bulking. 100 to 3,000.
goal.proteinGramsintegerMay be absent. Grams of protein for one meal, always a floor. 5 to 300.
takesarray of stringMay be absent. At most 16 items. Matches ^[a-z][a-z_.]{0,47}$.
hideobjectMay be absent.
hide.retailSuggestionsbooleanMay be absent.
hide.loyaltybooleanMay be absent.
cardActionsarray of objectMay be absent. At most 6 items.
cardActions[].tool"offer_to_order"
cardActions[].offeredAtstringAt most 40 characters.
cardActions[].outcome"added"
cardActions[].linesarray of object1 to 8 items.

ChatEvent

FieldTypeDescription
type"start"
conversationIdstringMay be absent. 1 to 200 characters.
messageIdstringMay be absent. 1 to 200 characters.
deltastringMay be absent.
cardIdstringMay be absent. 1 to 200 characters.
cardChatCardMay be absent.

ChatDone

FieldTypeDescription
finishReasonstringOne of stop, length, content_filter, aborted, error, other. An open list: read a value you don't know as other.

ChatCard

A card the waiter put on screen, with the dishes it shows. Fields per kind; an unknown kind reads as other.

FieldTypeDescription
kindstringOne of dishes, surprise_basket, quick_replies, dietary_filters, language_choice, staff_called, branch_info, booking_times, booking, saved, cart_proposal, order_offer, pay_offer, build, other. An open list: read a value you don't know as other.
dishesarray of DishSummaryMay be absent. At most 20 items.
layoutstringMay be absent. One of card, carousel, comparison, pairing, other. An open list: read a value you don't know as other.
framingstringMay be absent. At most 500 characters.
aspectstringMay be absent. At most 40 characters.
specialobjectMay be absent.
special.headlinestringAt most 200 characters.
special.blurbstring or nullAt most 500 characters.
allergenstringMay be absent. At most 200 characters.
verificationstringMay be absent. One of menu-data, text-match, other. An open list: read a value you don't know as other.
disclaimerstringMay be absent. At most 1,000 characters.
conflictsarray of objectMay be absent. At most 20 items.
conflicts[].allergenstringAt most 200 characters.
conflicts[].dishesarray of stringAt most 20 items. At most 200 characters.
buildobjectMay be absent.
build.buildIdstring1 to 64 characters.
build.dishDishSummary
build.sizestring or nullAt most 80 characters.
build.needsSizeboolean
build.groupsarray of objectAt most 20 items.
build.completeboolean
build.totalstringAn amount in minor units, as a string.
build.nutritionobject
build.goalFitstringMay be absent. One of fits, over, under, unknown, other. An open list: read a value you don't know as other.
basketsarray of objectMay be absent. At most 3 items.
baskets[].itemsarray of objectAt most 12 items.
baskets[].totalstringAn amount in minor units, as a string.
baskets[].nutritionobjectMay be absent.
baskets[].goalFitstringMay be absent. One of fits, over, under, unknown, other. An open list: read a value you don't know as other.
budgetstring or nullMay be absent. An amount in minor units, as a string.
goalobjectMay be absent.
goal.modestringOne of cutting, maintain, bulking, other. An open list: read a value you don't know as other.
goal.fitsarray of stringAt most 20 items. 1 to 200 characters.
goal.unknownarray of stringAt most 20 items. 1 to 200 characters.
promptsarray of stringMay be absent. At most 6 items. At most 60 characters.
tagsarray of stringMay be absent. At most 10 items. Each: One of vegan, vegetarian, gluten_free, halal, kosher, dairy_free, nut_free, keto, spicy, high_protein, other. An open list: read a value you don't know as other.
languagesarray of stringMay be absent. At most 12 items. A language tag, such as ar or en-GB.
staffCallobjectMay be absent.
staffCall.sourcestringOne of request, escalation, unknown. An open list: read a value you don't know as unknown.
staffCall.kindstringMay be absent. One of order_now, water, check, extra_napkins, refill, other. An open list: read a value you don't know as other.
staffCall.reasonstringMay be absent. One of diner_requested_staff, allergen_severe, off_menu_question, order_placement, complaint, reservation, payment, unknown_other. An open list: read a value you don't know as unknown_other.
staffCall.urgencystringMay be absent. One of normal, high, unknown. An open list: read a value you don't know as unknown.
staffCall.alreadySentboolean
branchInfoobjectMay be absent.
branchInfo.namestring or nullAt most 200 characters.
branchInfo.rowsarray of objectAt most 10 items.
bookingTimesobjectMay be absent.
bookingTimes.datestringMatches ^\d{4}-\d{2}-\d{2}$.
bookingTimes.dateLabelstringAt most 80 characters.
bookingTimes.timesarray of stringAt most 48 items. Matches ^(?:[01]\d|2[0-3]):[0-5]\d$.
bookingTimes.asRequestboolean
bookingobjectMay be absent.
booking.outcomestringOne of booked, already_booked, changed, cancelled, other. An open list: read a value you don't know as other.
booking.statusstringOne of requested, confirmed, cancelled, unknown. An open list: read a value you don't know as unknown.
booking.codestringAt most 40 characters.
booking.partySizeinteger1 to 500.
booking.startsAtstring (date-time)
booking.timezonestringAt most 60 characters.
booking.dateLabelstringAt most 80 characters.
booking.timestringAt most 20 characters.
booking.locationNamestringAt most 200 characters.
booking.confirmationNotestring or nullAt most 500 characters.
booking.bookingIdstringMay be absent. 1 to 200 characters.
booking.branchstringMay be absent. An address: lower-case letters, digits and dashes.
booking.datestringMay be absent. Matches ^\d{4}-\d{2}-\d{2}$.
booking.time24stringMay be absent. Matches ^(?:[01]\d|2[0-3]):[0-5]\d$.
savedDishSummaryMay be absent.
linesarray of objectMay be absent. At most 12 items.
lines[].lineIdstringUnique per proposed line: the host answers and dedupes by it. 1 to 200 characters.
lines[].dishIdstringTamr's id for the dish. 1 to 200 characters.
lines[].variantIdstring or nullTamr's id for the size; null for a dish sold in one size. 1 to 200 characters.
lines[].optionIdsarray of stringTamr's ids for the chosen options. At most 20 items. 1 to 200 characters.
lines[].externalIdstring or nullThe host's id for the dish at this branch; null when not mapped. 1 to 200 characters.
lines[].variantExternalIdstring or nullThe host's id for the size; null when not mapped. 1 to 200 characters.
lines[].optionExternalIdsarray of string or nullThe host's ids for the options, one per entry of optionIds; null where not mapped. At most 20 items.
lines[].titlestring1 to 200 characters.
lines[].variantLabelstring or nullThe size as the menu labels it; null for a dish with one size. 1 to 80 characters.
lines[].choicesarray of stringThe chosen options' names, in the order of optionIds. At most 20 items. 1 to 80 characters.
lines[].unitPricestringAn amount in minor units, as a string.
lines[].currencystringA three-letter currency code (ISO 4217).
lines[].imageUrlstring or nullMatches ^https:\/\/[^\s]+$.
lines[].quantityintegerHow many of the line. For a set, how many whole sets: picks included. 1 to 99.
lines[].notestring or nullThe diner's own request for the kitchen ("no onions"). 1 to 140 characters.
lines[].picksarray of objectMay be absent. A set's picks, in the order of its choices (#560). Absent on any other line. Each pick's count is per one set; quantity multiplies the whole set. At most 120 items.
lines[].treatobjectMay be absent. A treat on the house (#455): price this line at zero, then redeem the id once the order is placed. Absent on any other line.
offerobjectMay be absent.
offer.itemsarray of object1 to 8 items.
offer.framingstring or nullAt most 120 characters.
offer.offeredAtstring (date-time)
offer.addedbooleanMay be absent.
notAddedarray of objectMay be absent. At most 12 items.
notAdded[].dishIdstring1 to 200 characters.
notAdded[].namestring1 to 200 characters.
notAdded[].reasonstringOne of sold_out, not_served_now, size_required, choices_required, allergen_conflict, other. An open list: read a value you don't know as other.
reorderobjectMay be absent.
reorder.whichstringOne of usual, last, other. An open list: read a value you don't know as other.
reorder.placedAtstring (date-time)
reorder.droppedarray of objectAt most 100 items.

DishSummary

A dish as a card or the menu shows it: enough to draw it with no other call.

FieldTypeDescription
dishIdstring1 to 200 characters.
namestring1 to 200 characters.
pricestringAn amount in minor units, as a string.
currencystringA three-letter currency code (ISO 4217).
imageUrlstring or nullMatches ^https:\/\/[^\s]+$.
caloriesinteger or null0 to 9,007,199,254,740,991.
proteinGramsinteger or null0 to 9,007,199,254,740,991.
carbsGramsinteger or null0 to 9,007,199,254,740,991.
fatGramsinteger or null0 to 9,007,199,254,740,991.
allergensarray of stringAt most 10 items. Each: One of gluten, dairy, egg, nuts, sesame, soy, fish, shellfish, peanut, mustard.
dietaryTagsarray of stringAt most 11 items. Each: One of vegan, vegetarian, gluten_free, halal, kosher, dairy_free, nut_free, keto, spicy, high_protein, other. An open list: read a value you don't know as other.
availableboolean
externalIdstring or null1 to 200 characters.
FieldTypeDescription
menuobject
menu.namestring1 to 200 characters.
menu.localestringA language tag, such as ar or en-GB.
menu.currencystringA three-letter currency code (ISO 4217).
categoriesarray of object
categories[].namestring1 to 200 characters.
categories[].dishesarray of object

CatalogMenuResponse

One published menu as the host's backend keeps it: the dishes exactly as GET /api/v1/menu lists them, with the menu's ids and version.

FieldTypeDescription
menuobject
menu.menuIdstring1 to 200 characters.
menu.menuSlugstring1 to 200 characters.
menu.namestring1 to 200 characters.
menu.localestringA language tag, such as ar or en-GB.
menu.currencystringA three-letter currency code (ISO 4217).
menu.modesarray of stringAt most 3 items. Each: One of dine_in, pickup, delivery.
menu.branchstring or nullAn address: lower-case letters, digits and dashes.
menu.versioninteger0 to 9,007,199,254,740,991.
menu.updatedAtstring (date-time)
categoriesarray of object
categories[].namestring1 to 200 characters.
categories[].dishesarray of object

WaiterFace

FieldTypeDescription
namestring1 to 60 characters.
avatarLetterstring1 to 2 characters.
greetingstring1 to 500 characters.
startersarray of stringAt most 8 items. 1 to 80 characters.
voiceboolean
languagesarray of stringAt most 12 items. A language tag, such as ar or en-GB.
brandobjectMay be absent. The restaurant's brand: the menu's kit over the organization's. Every field optional.
brand.accentstringMay be absent. Matches ^#[0-9a-fA-F]{6}$.
brand.accentSecondarystringMay be absent. Matches ^#[0-9a-fA-F]{6}$.
brand.paperstringMay be absent. Matches ^#[0-9a-fA-F]{6}$.
brand.displayFontstringMay be absent. One of fraunces, cormorant, playfair, dm-serif, eb-garamond, crimson, other. An open list: read a value you don't know as other.
brand.uiFontstringMay be absent. One of geist, inter, system, manrope, sora, dm-sans, other. An open list: read a value you don't know as other.
brand.displayFontUrlstringMay be absent. Matches ^https:\/\/[^\s]+$.
brand.uiFontUrlstringMay be absent. Matches ^https:\/\/[^\s]+$.
brand.logoUrlstringMay be absent. Matches ^https:\/\/[^\s]+$.
ordersGoTostringOne of tamr, app_cart. An open list: read a value you don't know as tamr.
ordersGoToByModeobjectMay be absent. Where orders go for each way of ordering, over ordersGoTo. A way left out goes where ordersGoTo says.
ordersGoToByMode.dine_instringMay be absent. One of tamr, app_cart. An open list: read a value you don't know as tamr.
ordersGoToByMode.pickupstringMay be absent. One of tamr, app_cart. An open list: read a value you don't know as tamr.
ordersGoToByMode.deliverystringMay be absent. One of tamr, app_cart. An open list: read a value you don't know as tamr.
appobjectMay be absent. The restaurant's settings for the waiter in its app, between the menu's brand and the app's overrides. Every field but allowCustomise may be left out.
app.lookobjectMay be absent.
app.shownobjectMay be absent.
app.wordingobjectMay be absent.
app.startersobjectMay be absent.
app.allowCustomiseboolean

ConversationList

FieldTypeDescription
conversationsarray of objectAt most 50 items.
conversations[].conversationIdstring1 to 200 characters.
conversations[].statusstringOne of active, resolved, escalated, fallback, abandoned, unknown. An open list: read a value you don't know as unknown.
conversations[].channelstringOne of qr, widget, app, mcp, unknown. An open list: read a value you don't know as unknown.
conversations[].localestring or nullA language tag, such as ar or en-GB.
conversations[].startedAtstring (date-time)
conversations[].updatedAtstring (date-time)
conversations[].titlestring or nullAt most 200 characters.

ConversationResponse

FieldTypeDescription
conversationIdstring1 to 200 characters.
statusstringOne of active, resolved, escalated, fallback, abandoned, unknown. An open list: read a value you don't know as unknown.
channelstringOne of qr, widget, app, mcp, unknown. An open list: read a value you don't know as unknown.
localestring or nullA language tag, such as ar or en-GB.
startedAtstring (date-time)
updatedAtstring (date-time)
messagesarray of object
messages[].messageIdstring1 to 200 characters.
messages[].rolestringOne of diner, waiter, other. An open list: read a value you don't know as other.
messages[].createdAtstring (date-time)
messages[].textstring or null
messages[].cardsarray of ChatCard

ClientApiErrorData

FieldTypeDescription
codestringOne of app_key_invalid, sdk_disabled, origin_not_allowed, session_expired, token_invalid, token_replayed, code_invalid, guest_not_allowed, unavailable, rate_limited, menu_unavailable, after_hours_closed, waiter_resting, test_limit_reached, max_turns_reached, message_rejected, nothing_heard, invalid_request, not_found, table_refused, pay_refused, pickup_refused, review_refused, identity_required, treat_refused, other. An open list: read a value you don't know as other.
requestIdstringMay be absent. At most 128 characters.
retryAfterintegerMay be absent. 0 to 9,007,199,254,740,991.
refusalstringMay be absent. One of unknown_table, table_off_plan, no_table, table_cleared, stale, ordering_off, paused, closed, unavailable, test_key, other. An open list: read a value you don't know as other.
problemsarray of objectMay be absent. At most 60 items.
problems[].dishIdstring1 to 200 characters.
problems[].namestring or nullAt most 200 characters.
problems[].problemstringOne of gone, sold_out, not_served_now, size_required, size_gone, choices_required, quantity, other. An open list: read a value you don't know as other.
pausedUntilstring (date-time)May be absent.
payRefusalstringMay be absent. One of not_enabled, paused, no_provider, provider_not_available, test_key, orders_to_app, invalid_amount, below_minimum, above_maximum, tip_too_large, tips_off, daily_cap, wallet_full, monthly_cap, payment_in_progress, already_paid, provider_unavailable, provider_error, table_already_paid, tab_not_found, typed_amount_off, tab_nothing_owed, tab_amount_over, tab_changed, other. An open list: read a value you don't know as other.
pickupRefusalstringMay be absent. One of ordering_off, no_branch, paused, closed, pickup_time, details, blocked, too_large, unavailable, catering_menu, test_key, other. An open list: read a value you don't know as other.
reviewRefusalstringMay be absent. One of order_not_found, order_closed, too_old, nothing_to_review, other. An open list: read a value you don't know as other.
treatRefusalstringMay be absent. One of withdrawn, expired, already_redeemed, other. An open list: read a value you don't know as other.
amountstringMay be absent. An amount in minor units, as a string.
paymentIdstringMay be absent. 1 to 200 characters.
fallbackobjectMay be absent.
fallback.namestringAt most 200 characters.
fallback.phonestring or nullAt most 40 characters.
fallback.messagestringAt most 500 characters.

ConversationEndedEvent

FieldTypeDescription
type"conversation.ended"
timestampstring (date-time)
livemodeboolean
dataobject
data.conversationIdstring1 to 200 characters.
data.appKeyIdstring1 to 200 characters.
data.externalUserIdstring or null1 to 200 characters.
data.branchstring or nullAn address: lower-case letters, digits and dashes.
data.reasonstringOne of resolved, idle, new_chat, logged_out, unknown. An open list: read a value you don't know as unknown.
data.startedAtstring (date-time)
data.endedAtstring (date-time)
data.staffCalledboolean
data.messageCountinteger0 to 9,007,199,254,740,991.

CartProposedEvent

FieldTypeDescription
type"cart.proposed"
timestampstring (date-time)
livemodeboolean
dataobject
data.conversationIdstring1 to 200 characters.
data.externalUserIdstring or null1 to 200 characters.
data.proposalIdstring1 to 200 characters.
data.linesarray of object1 to 50 items.

StaffRequestedEvent

FieldTypeDescription
type"staff.requested"
timestampstring (date-time)
livemodeboolean
dataobject
data.conversationIdstring1 to 200 characters.
data.externalUserIdstring or null1 to 200 characters.
data.branchstring or nullAn address: lower-case letters, digits and dashes.
data.tablestring or null1 to 40 characters.
data.sourcestringOne of request, escalation, unknown. An open list: read a value you don't know as unknown.
data.kindstringMay be absent. One of order_now, water, check, extra_napkins, refill, other. An open list: read a value you don't know as other.
data.reasonstringMay be absent. One of diner_requested_staff, allergen_severe, off_menu_question, order_placement, complaint, reservation, payment, unknown_other. An open list: read a value you don't know as unknown_other.
data.urgencystringMay be absent. One of normal, high, unknown. An open list: read a value you don't know as unknown.

BookingMadeEvent

FieldTypeDescription
type"booking.made"
timestampstring (date-time)
livemodeboolean
dataobject
data.conversationIdstring1 to 200 characters.
data.externalUserIdstring or null1 to 200 characters.
data.bookingIdstring1 to 200 characters.
data.statusstringOne of requested, confirmed, cancelled, unknown. An open list: read a value you don't know as unknown.
data.branchstringAn address: lower-case letters, digits and dashes.
data.datestringMatches ^\d{4}-\d{2}-\d{2}$.
data.timestringMatches ^(?:[01]\d|2[0-3]):[0-5]\d$.
data.partySizeinteger1 to 500.

BookingChangedEvent

FieldTypeDescription
type"booking.changed"
timestampstring (date-time)
livemodeboolean
dataobject
data.conversationIdstring1 to 200 characters.
data.externalUserIdstring or null1 to 200 characters.
data.bookingIdstring1 to 200 characters.
data.statusstringOne of requested, confirmed, cancelled, unknown. An open list: read a value you don't know as unknown.
data.branchstringAn address: lower-case letters, digits and dashes.
data.datestringMatches ^\d{4}-\d{2}-\d{2}$.
data.timestringMatches ^(?:[01]\d|2[0-3]):[0-5]\d$.
data.partySizeinteger1 to 500.

OrderPlacedEvent

FieldTypeDescription
type"order.placed"
timestampstring (date-time)
livemodeboolean
dataobject
data.externalUserIdstring or null1 to 200 characters.
data.conversationIdstring or null1 to 200 characters.
data.orderIdstring1 to 200 characters.
data.numberintegerThe short number staff call out, per branch and service day. -9,007,199,254,740,991 to 9,007,199,254,740,991.
data.statusstringOne of awaiting_payment, sent, accepted, served, declined, cancelled, expired, unknown. An open list: read a value you don't know as unknown.
data.branchstringAn address: lower-case letters, digits and dashes.
data.tablestring or null1 to 40 characters.
data.currencystringA three-letter currency code (ISO 4217).
data.subtotalstringAn amount in minor units, as a string.
data.linesarray of object1 to 100 items.
data.fulfilmentstringMay be absent. One of dine_in, pickup, unknown. An open list: read a value you don't know as unknown.
data.pickupAtstring (date-time) or nullMay be absent.
data.pickupCodestring or nullMay be absent. 1 to 12 characters.
data.testbooleanMay be absent.

OrderCancelledEvent

FieldTypeDescription
type"order.cancelled"
timestampstring (date-time)
livemodeboolean
dataobject
data.externalUserIdstring or null1 to 200 characters.
data.orderIdstring1 to 200 characters.
data.statusstringOne of awaiting_payment, sent, accepted, served, declined, cancelled, expired, unknown. An open list: read a value you don't know as unknown.
data.bystringOne of restaurant, diner, time, unknown. An open list: read a value you don't know as unknown.

PaymentCompletedEvent

FieldTypeDescription
type"payment.completed"
timestampstring (date-time)
livemodeboolean
dataobject
data.externalUserIdstring or null1 to 200 characters.
data.conversationIdstring or null1 to 200 characters.
data.paymentIdstring1 to 200 characters.
data.referencestring1 to 40 characters.
data.amountstringAn amount in minor units, as a string.
data.tipstringAn amount in minor units, as a string.
data.currencystringA three-letter currency code (ISO 4217).
data.orderIdstring or null1 to 200 characters.
data.branchstringAn address: lower-case letters, digits and dashes.
data.tablestring or null1 to 40 characters.

ReviewSubmittedEvent

FieldTypeDescription
type"review.submitted"
timestampstring (date-time)
livemodeboolean
dataobject
data.reviewIdstring1 to 200 characters.
data.externalUserIdstring1 to 200 characters.
data.externalOrderIdstring or null1 to 200 characters.
data.conversationIdstring or null1 to 200 characters.
data.dishIdstring1 to 200 characters.
data.externalIdstring or null1 to 200 characters.
data.ratinginteger1 to 5.
data.submittedAtstring (date-time)
FieldTypeDescription
type"menu.changed"
timestampstring (date-time)
livemodeboolean
dataobject
data.menuIdstring1 to 200 characters.
data.menuSlugstring1 to 200 characters.
data.publishedboolean
data.modesarray of stringAt most 3 items. Each: One of dine_in, pickup, delivery.
data.branchesarray of objectAt most 500 items.
data.versioninteger0 to 9,007,199,254,740,991.
data.reasonstringOne of content, external_ids, back_on_sale, other. An open list: read a value you don't know as other.
data.changedAtstring (date-time)
data.dishIdsarray of stringMay be absent. At most 500 items. 1 to 200 characters.

ClientApiError

FieldTypeDescription
definedboolean
codestring
statusinteger
messagestring
dataClientApiErrorDataMay be absent.