GET/v1/conversations/{conversation_id}beta

Get a conversation and its 24-hour window

Needs: Read your data (mcp:read)
Plan: Any plan with API access
Limits: 300 a minute per key
Undo: Nothing to undo: this only reads.

Returns one conversation with its contact, assignee, tags, the reply window and the latest messages. Reading it does not mark anything as read.

window is the source of truth for replying: applies is true on WhatsApp, Instagram, Messenger and TikTok (false on web chat, where open is always true); open says whether a free-form reply can be sent now, decided exactly as the reply itself is; closes_at (UTC) is when an open window closes, or null when that is not known; a closed window has a reason: expired (it closed at closed_at) or never_opened (the customer has not written on this channel). To check the window alone, ask with last_messages=0.

Try it

Example

Path

conversation_idrequiredstring

The conversation id.

Query (1)

last_messagesoptionalinteger

How many recent messages to include (0–20).

This only reads. It uses your real data and changes nothing.

curl -X GET 'https://mcp.wa-api.cloud/v1/conversations/77410' \
  -H "Authorization: Bearer $API_KEY"

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
conversation_idrequired	string · path	The conversation id.pattern `^\d{1,19}$`Signed in? Pick one from your data with “My data”.
last_messages	integer · query	How many recent messages to include (0–20).0–20 · default `5`

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`

Response `200`

The conversation.

Response fields
Field	Type	What it is
conversationrequired	object
idrequired	string
staterequired	string	open \| closed
contactrequired	object or null	null when the contact was deleted.
idrequired	string
namerequired	string
phonerequired	string or null
dnd_enabledrequired	boolean
groupsrequired	array of string
channelrequired	object
idrequired	string
namerequired	string or null
typerequired	string or null
assigneerequired	object or null
staff_idrequired	string
namerequired	string or null
team_idrequired	string or null
assigned_atrequired	string or null
tagsrequired	array of object
idrequired	string
namerequired	string
starredrequired	boolean
unread_countrequired	number
reply_statusrequired	string or null	incoming_no_reply = customer is waiting; outgoing_no_response = waiting on the customer.
slarequired	object or null
statusrequired	string
next_due_atrequired	string or null
next_due_metricrequired	string or null
policyrequired	string or null
reminder_atrequired	string or null
whatsapp_window_expires_atrequired	string or null	Raw window end as stored, kept for compatibility. Use `window` to decide whether a free-form reply can be sent.
windowrequired	object	The reply window, decided exactly as a send decides it. The source of truth for "can I reply free-form now".
appliesrequired	boolean	true on channels with a reply window (WhatsApp, Instagram, Messenger, TikTok); false on web chat and custom channels.
openrequired	boolean	true = a free-form reply can be sent now (always true when the window does not apply). false = only an approved template reaches the customer.
kindrequired	string or null	service (24 h), free_entry (72 h after an ad), standard, tiktok (48 h), web.
closes_atrequired	string or null	Open window: when it closes (UTC ISO-8601); null when unknown or when no window applies.
closed_atrequired	string or null	Closed window: when it closed (UTC); null when the customer never opened one.
reasonrequired	string or null	Why: no_window (the channel has none), expired (it closed at closedAt), never_opened (no customer message on this channel yet); null while open.one of: `no_window`, `expired`, `never_opened`
bot_activerequired	boolean
last_messagerequired	object or null
idrequired	string
conversation_idrequired	string or null
typerequired	string	TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT, STICKER, LOCATION, TEMPLATE, INTERACTIVE, ORDER, CONTACTS, SYSTEM
directionrequired	string	one of: `inbound`, `outbound`, `system`
statusrequired	string	received (inbound) \| pending \| sent \| delivered \| read \| failed \| system
textrequired	string or null	Message text, or the caption for media. Media files/URLs are never included.
text_truncatedrequired	boolean
has_mediarequired	boolean
fromrequired	object or null	Who sent an outbound message (staff or bot); null for inbound.
reply_to_idrequired	string or null
errorrequired	string or null
created_atrequired	string or null
created_atrequired	string or null
updated_atrequired	string or null
episode_titlerequired	string or null
permissionsrequired	object	What the connected staff member may do on this conversation (assign, close, …).
last_messagesrequired	array of object	Newest first.
idrequired	string
conversation_idrequired	string or null
typerequired	string	TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT, STICKER, LOCATION, TEMPLATE, INTERACTIVE, ORDER, CONTACTS, SYSTEM
directionrequired	string	one of: `inbound`, `outbound`, `system`
statusrequired	string	received (inbound) \| pending \| sent \| delivered \| read \| failed \| system
textrequired	string or null	Message text, or the caption for media. Media files/URLs are never included.
text_truncatedrequired	boolean
has_mediarequired	boolean
fromrequired	object or null	Who sent an outbound message (staff or bot); null for inbound.
staff_idrequired	string or null
staff_namerequired	string or null
botrequired	boolean
reply_to_idrequired	string or null
errorrequired	string or null
created_atrequired	string or null

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
404	not_found	No conversation with this id, or your key cannot see it.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.

Examples

Read a conversation

Response 200

{
  "conversation": {
    "id": "77410",
    "state": "open",
    "contact": {
      "id": "48213",
      "name": "Jane Doe",
      "phone": "+15555550123",
      "dnd_enabled": false,
      "groups": []
    },
    "channel": {
      "id": "301",
      "name": "Main WhatsApp",
      "type": "whatsapp"
    },
    "assignee": null,
    "team_id": null,
    "tags": [
      {
        "id": "4",
        "name": "new-lead"
      }
    ],
    "unread_count": 2,
    "reply_status": "incoming_no_reply",
    "whatsapp_window_expires_at": "2026-09-25T09:12:00Z",
    "window": {
      "applies": true,
      "open": true,
      "kind": "service",
      "closes_at": "2026-09-25T09:12:00.000Z",
      "closed_at": null,
      "reason": null
    },
    "last_message": {
      "id": "5501234",
      "type": "TEXT",
      "direction": "inbound",
      "status": "received",
      "text": "Hi, is the blue one in stock?",
      "created_at": "2026-09-24T09:12:00Z",
      "conversation_id": null,
      "text_truncated": false,
      "has_media": false,
      "from": null,
      "reply_to_id": null,
      "error": null
    },
    "created_at": "2026-09-24T09:11:40Z",
    "updated_at": "2026-09-24T09:12:00Z",
    "assigned_at": null,
    "starred": false,
    "sla": null,
    "reminder_at": null,
    "bot_active": false
  },
  "last_messages": [
    {
      "id": "5501234",
      "type": "TEXT",
      "direction": "inbound",
      "status": "received",
      "text": "Hi, is the blue one in stock?",
      "created_at": "2026-09-24T09:12:00Z",
      "conversation_id": null,
      "text_truncated": false,
      "has_media": false,
      "from": null,
      "reply_to_id": null,
      "error": null
    }
  ],
  "episode_title": null,
  "permissions": {}
}

Check if the 24-hour reply window (customer service window, WhatsApp session) is open before replying

Response 200

{
  "conversation": {
    "id": "77410",
    "state": "open",
    "contact": {
      "id": "48213",
      "name": "Jane Doe",
      "phone": "+15555550123",
      "dnd_enabled": false,
      "groups": []
    },
    "channel": {
      "id": "301",
      "name": "Main WhatsApp",
      "type": "whatsapp"
    },
    "assignee": null,
    "team_id": null,
    "tags": [
      {
        "id": "4",
        "name": "new-lead"
      }
    ],
    "unread_count": 2,
    "reply_status": "incoming_no_reply",
    "whatsapp_window_expires_at": "2026-09-25T09:12:00Z",
    "window": {
      "applies": true,
      "open": false,
      "kind": "service",
      "closes_at": null,
      "closed_at": "2026-09-25T09:12:00.000Z",
      "reason": "expired"
    },
    "last_message": {
      "id": "5501234",
      "type": "TEXT",
      "direction": "inbound",
      "status": "received",
      "text": "Hi, is the blue one in stock?",
      "created_at": "2026-09-24T09:12:00Z",
      "conversation_id": null,
      "text_truncated": false,
      "has_media": false,
      "from": null,
      "reply_to_id": null,
      "error": null
    },
    "created_at": "2026-09-24T09:11:40Z",
    "updated_at": "2026-09-24T09:12:00Z",
    "assigned_at": null,
    "starred": false,
    "sla": null,
    "reminder_at": null,
    "bot_active": false
  },
  "last_messages": [],
  "episode_title": null,
  "permissions": {}
}

Operation path

The same operation is also at POST /v1/ops/inbox_get_conversation, with every field in the JSON body.

Try it

Code and response

Parameters

Headers

Response 200

Errors

Examples

Operation path

Response `200`