List WhatsApp conversations
List WhatsApp conversations (tickets) on one of the project's WhatsApp numbers, with optional filtering by assignment and status, plus search by the customer's phone number or message text. Results are paginated and the response includes a meta block with counts for each assignment bucket (all, mine, unassigned, assigned) so you can render conversation tabs. This is the generic conversation listing endpoint — use the POST /filter variant for structured filters or the by-contact endpoint to scope to a single contact.
curl --request GET \
--url 'https://api.nabrah.ai/api/ext/omni_v2/whatsapp' \
--header 'X-API-Key: <your-api-key>'{
"meta": {
"all_count": 0,
"mine_count": 0,
"unassigned_count": 0,
"assigned_count": 0
},
"payload": [
{
"account_id": 0,
"additional_attributes": {},
"agent_last_seen_at": 0,
"assignee_last_seen_at": 0,
"can_reply": false,
"contact_last_seen_at": 0,
"created_at": 0,
"custom_attributes": {},
"first_reply_created_at": 0,
"id": 0,
"inbox_id": 0,
"labels": [
"string"
],
"last_activity_at": 0,
"last_non_activity_message": {
"account_id": 0,
"additional_attributes": {},
"content": "string",
"content_attributes": {},
"content_type": "string",
"conversation": null,
"conversation_id": 0,
"created_at": 0,
"external_source_ids": {},
"id": 0,
"inbox_id": 0,
"message_type": 0,
"private": false,
"processed_message_content": "string",
"sender": null,
"sender_id": 0,
"sender_type": "string",
"sentiment": {},
"source_id": "string",
"status": "string",
"updated_at": "string",
"attachments": []
},
"messages": [
{
"account_id": null,
"additional_attributes": null,
"content": null,
"content_attributes": null,
"content_type": null,
"conversation": null,
"conversation_id": null,
"created_at": null,
"external_source_ids": null,
"id": null,
"inbox_id": null,
"message_type": null,
"private": null,
"processed_message_content": null,
"sender": null,
"sender_id": null,
"sender_type": null,
"sentiment": null,
"source_id": null,
"status": null,
"updated_at": null,
"attachments": null
}
],
"meta": {
"channel": "string",
"hmac_verified": false,
"sender": null,
"assignee": null
},
"muted": false,
"priority": "string",
"sla_policy_id": 0,
"snoozed_until": 0,
"status": "string",
"timestamp": 0,
"unread_count": 0,
"updated_at": 0
}
]
}Pagination & counts
The endpoint returns one page of conversations at a time inside payload, plus aggregate meta counts.
pagePass ?page=1 for the first page and increment to walk subsequent pages. When a page returns fewer items than the page size (or an empty payload), you have reached the end.
meta.all_count, meta.mine_count, meta.unassigned_count, and meta.assigned_count reflect the totals for each assignment bucket and are independent of the current page.
all_countmine_countunassigned_countassigned_countReading conversations
Each item in payload is a conversation. Useful fields: id (the conversation/ticket id), inbox_id (which WhatsApp number it belongs to), status, unread_count, and last_non_activity_message (the most recent real message).
Authenticate every request with the X-API-Key header. The key is scoped to a single project, so no project_id is required.
Choosing the WhatsApp number
A project can connect more than one WhatsApp number. inbox_id selects the number this call works on.
inbox_id is optional; the project's only WhatsApp number is used.
inbox_id is required and the call returns 400 without it. An id that is not one of the project's WhatsApp numbers returns 404.
inbox_idList the numbers and their ids with GET /api/ext/omni_v2/whatsapp/inboxes.
Authorization
X-API-KeystringheaderrequiredYour workspace API key. Create one in the dashboard under API keys.
Query parameters
assignee_typeenum(all | me | unassigned | assigned)Filter conversations by assignment relative to the API key's identity.
One of all, me, unassigned, or assigned. Defaults to all when omitted.
status_paramenum(open | pending | resolved | snoozed | all)Filter conversations by their workflow status.
One of open, pending, resolved, snoozed, or all. Defaults to open when omitted.
qstringSearch by the customer's phone number or by message text.
A phone number returns every conversation of the contacts whose number matches. It can be international (+966500000001), local (0500000001), partial (at least 4 digits), and may contain spaces, dashes, dots or brackets. Arabic-Indic digits are accepted. Any other text is matched against message content. Optional; leave empty to disable search. A number with no conversation yet, for example one that has never written to you, returns nothing; open one with POST /api/ext/omni_v2/whatsapp.
pageinteger1-based page number for paginating results.
Optional; defaults to the first page when omitted.
inbox_idstringThe id of the WhatsApp number to use, from GET /api/ext/omni_v2/whatsapp/inboxes.
Use inboxes[].id (a UUID), not the numeric inboxes[].inbox_id. Optional while the project has one WhatsApp number; required once it has more than one.
Response
Successful Response
application/json
Validation Error
application/json