Get a conversation

Read one of the diner's conversations with every message and card, to redraw a chat after a reload or on another device.

GET/api/v1/conversations/{conversationId}Client API

One conversation with its messages and the cards they carried, to redraw a chat after a reload or on another device. A replayed order_offer card can carry offer.added: true: draw it as already added. Another diner's conversation reads as not_found.

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.

Path parameters

NameTypeRequiredDescription
conversationIdstringYes1 to 200 characters.

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_-]+)+$.

Response

A 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

Example

curl https://tamr.link/api/v1/conversations/cmconv0001 \
  -H "x-tamr-key: $TAMR_APP_KEY" \
  -H "x-tamr-session: $TAMR_SESSION"

Example response

{
  "conversationId": "cmconv0001",
  "status": "active",
  "channel": "app",
  "locale": "en",
  "startedAt": "2026-10-28T08:00:00Z",
  "updatedAt": "2026-10-28T08:05:00Z",
  "messages": [
    {
      "messageId": "m1",
      "role": "diner",
      "createdAt": "2026-10-28T08:00:01Z",
      "text": "Something light?",
      "cards": []
    },
    {
      "messageId": "m2",
      "role": "waiter",
      "createdAt": "2026-10-28T08:00:04Z",
      "text": "Try these.",
      "cards": [
        {
          "kind": "dishes",
          "layout": "carousel",
          "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"
            }
          ]
        },
        {
          "kind": "order_offer",
          "offer": {
            "items": [
              {
                "dish": {
                  "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"
                },
                "quantity": 2,
                "size": null,
                "choices": [],
                "note": "No onions",
                "dishSizes": [
                  {
                    "variantId": "var_large",
                    "label": "Large",
                    "price": "1500",
                    "externalId": null
                  }
                ],
                "dishChoices": [
                  {
                    "name": "Bread",
                    "min": 1,
                    "max": 1,
                    "options": [
                      {
                        "optionId": "opt_saj",
                        "name": "Saj",
                        "price": null,
                        "extra": null,
                        "calories": null,
                        "proteinGrams": null,
                        "carbsGrams": null,
                        "fatGrams": null,
                        "allergens": [],
                        "externalId": null
                      }
                    ]
                  }
                ]
              }
            ],
            "framing": null,
            "offeredAt": "2026-11-04T19:40:00.000Z",
            "added": true
          }
        }
      ]
    }
  ]
}

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.
not_found404Not this diner's, or doesn't exist. The two read the same on purpose.