# List WhatsApp conversations

> GET https://api.nabrah.ai/api/ext/omni_v2/whatsapp

Group: WhatsApp. Page: https://www.nabrah.ai/en/docs/api-reference/whatsapp/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.

## Pagination & counts

The endpoint returns one page of conversations at a time inside `payload`, plus aggregate `meta` counts.

- **page**: Pass `?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 counts**: `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. Fields: `all_count`, `mine_count`, `unassigned_count`, `assigned_count`.

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

- **One number**: `inbox_id` is optional; the project's only WhatsApp number is used.
- **More than one number**: `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. Fields: `inbox_id`.

List the numbers and their ids with GET /api/ext/omni_v2/whatsapp/inboxes.

## Authorization

- `X-API-Key` (string, header, required): your workspace API key.

## Query parameters

- `assignee_type` (enum(all | me | unassigned | assigned), optional): Filter conversations by assignment relative to the API key's identity. One of `all`, `me`, `unassigned`, or `assigned`. Defaults to `all` when omitted.
- `status_param` (enum(open | pending | resolved | snoozed | all), optional): Filter conversations by their workflow status. One of `open`, `pending`, `resolved`, `snoozed`, or `all`. Defaults to `open` when omitted.
- `q` (string, optional): Search 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.
- `page` (integer, optional): 1-based page number for paginating results. Optional; defaults to the first page when omitted.
- `inbox_id` (string, optional): The `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

### 200 Successful Response

Content type: `application/json`

```json
{
  "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
    }
  ]
}
```

### 422 Validation Error

Content type: `application/json`

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```

## Request examples

### cURL

```bash
curl --request GET \
  --url 'https://api.nabrah.ai/api/ext/omni_v2/whatsapp' \
  --header 'X-API-Key: <your-api-key>'
```

### Python

```python
import requests

url = "https://api.nabrah.ai/api/ext/omni_v2/whatsapp"
headers = {"X-API-Key": "<your-api-key>"}

response = requests.get(url, headers=headers)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.nabrah.ai/api/ext/omni_v2/whatsapp", {
  method: "GET",
  headers: { "X-API-Key": "<your-api-key>" },
});

const data = await response.json();
console.log(data);
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.nabrah.ai/api/ext/omni_v2/whatsapp", nil)
	req.Header.Set("X-API-Key", "<your-api-key>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```