# 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.

Source: https://tamr.link/docs/api/get-conversation

`GET https://tamr.link/api/v1/conversations/{conversationId}`

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](https://tamr.link/docs/api/start-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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `conversationId` | string | Yes | 1 to 200 characters. |

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `x-tamr-device` | string | No | Guest sessions only: the device id the session was exchanged with. Matches `^[A-Za-z0-9_-]{8,128}$`. |
| `x-tamr-app` | string | No | Native 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](https://tamr.link/docs/api/schemas#conversationresponse).

| Field | Type | Description |
| --- | --- | --- |
| `conversationId` | string | 1 to 200 characters. |
| `status` | string | One of `active`, `resolved`, `escalated`, `fallback`, `abandoned`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `channel` | string | One of `qr`, `widget`, `app`, `mcp`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `locale` | string or null | A language tag, such as `ar` or `en-GB`. |
| `startedAt` | string (date-time) |  |
| `updatedAt` | string (date-time) |  |
| `messages` | array of object |  |
| `messages[].messageId` | string | 1 to 200 characters. |
| `messages[].role` | string | One of `diner`, `waiter`, `other`. An open list: read a value you don't know as `other`. |
| `messages[].createdAt` | string (date-time) |  |
| `messages[].text` | string or null |  |
| `messages[].cards` | array of [ChatCard](https://tamr.link/docs/api/schemas#chatcard) |  |

## Example

curl:

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

Node:

```js
import { createClient } from "@tamr/api";

const tamr = createClient({ appKey: process.env.TAMR_APP_KEY });
// Sign the diner in first, with a token your backend signed (or a launch code).
await tamr.startSession({ token: dinerToken });

const result = await tamr.conversationsGet("cmconv0001");
console.log(result);
```

Python:

```python
import os

import requests

API = "https://tamr.link/api/v1"
headers = {
    "x-tamr-key": os.environ["TAMR_APP_KEY"],
    "x-tamr-session": os.environ["TAMR_SESSION"],  # from POST /api/v1/sdk/session
}
conversation_id = "cmconv0001"

response = requests.get(
    f"{API}/conversations/{conversation_id}",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

## Example response

```json
{
  "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](https://tamr.link/docs/errors).

| `data.code` | Status | What to do |
| --- | --- | --- |
| `app_key_invalid` | 401 | The key is wrong, revoked or of another kind. Check it in the dashboard. |
| `sdk_disabled` | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |
| `origin_not_allowed` | 403 | A browser called from an origin the key doesn't list. Add the origin to the key. |
| `session_expired` | 401 | Start a new session with a fresh token or code, then send the call again once. |
| `invalid_request` | 400 | A field doesn't match the spec. The message says which. |
| `rate_limited` | 429 | Wait `retryAfter` seconds (also in the `Retry-After` header), then try again. |
| `not_found` | 404 | Not this diner's, or doesn't exist. The two read the same on purpose. |
