/v1/conversationsbetaList conversations
- 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.
Finds inbox conversations, newest activity first. Filter by state, assignee, tags, channel or whether the customer is waiting for a reply.
Each conversation has a window: whether a free-form reply can be sent right now (open), and until when (closes_at, UTC). It is decided exactly as a reply is, so open: false means a reply would be refused with window_closed (send an approved template instead). whatsapp_window_expires_at is the raw stored time, kept for compatibility: decide with window.
Try it
Query (7)
Contact name or phone contains.
open or closed.
`false` = the unassigned queue.
Only this channel.
`incoming_no_reply` = the customer is waiting.
How many items per page (1–100).
The `next_cursor` from the previous page. Cursors expire after 24 hours.
This only reads. It uses your real data and changes nothing.
Code and response
curl -X GET 'https://mcp.wa-api.cloud/v1/conversations?state=open&reply_status=incoming_no_reply' \ -H "Authorization: Bearer $API_KEY"
The code reads your key from $API_KEY.
Parameters
| Field | Type | What it is |
|---|---|---|
| query | string · query | Contact name or phone contains.1–255 characters |
| state | string · query | open or closed.one of: open, closed |
| assigned | boolean · query | false = the unassigned queue. |
| channel_id | string · query | Only this channel.pattern ^\d{1,19}$Signed in? Pick one from your data with “My data”. |
| reply_status | string · query | incoming_no_reply = the customer is waiting.one of: incoming_no_reply, outgoing_no_response |
| limit | integer · query | How many items per page (1–100).1–100 · default 25 |
| cursor | string · query | The next_cursor from the previous page. Cursors expire after 24 hours.1–2048 characters |
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
A page of conversations.
| Field | Type | What it is |
|---|---|---|
| datarequired | array of 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 | |
| next_cursorrequired | string or null | Pass as "cursor" to get the next page; null when there are no more results. |
Errors
Errors are application/problem+json. Branch on code.
| Status | Code | When |
|---|---|---|
| 400 | invalid_input | A field is missing or has the wrong format. |
| 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 ( |
| 403 | insufficient_scope | The key does not have the permission this operation needs. |
| 429 | rate_limited | The key or workspace went over its rate limit. Wait for |
| 503 | upstream_unavailable | A service behind the API is briefly unavailable. Safe to retry with backoff. |
Examples
Customers waiting for a reply
Response 200
{
"data": [
{
"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
}
],
"next_cursor": null
}Operation path
The same operation is also at POST /v1/ops/inbox_search_conversations, with every field in the JSON body.