> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pingback.live/llms.txt
> Use this file to discover all available pages before exploring further.

# List Conversations

> Get a paginated list of all conversations for your business.

## Overview

Returns a list of conversations for your business, ordered by most recently updated. You can filter by status or assignee, and paginate through results.

## Request

**Method**: `GET`
**URL**: `/api/v1/conversations/`

### Headers

| Header        | Value          |
| ------------- | -------------- |
| Authorization | Bearer {token} |

### Query parameters

<ParamField query="status" type="string">
  Filter conversations by status. One of `"open"`, `"pending"`, `"resolved"`, or `"closed"`. Omit to return all statuses.
</ParamField>

<ParamField query="assignee_id" type="integer">
  Filter conversations assigned to a specific agent by their user ID.
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results per page. Defaults to `50`.
</ParamField>

## Response

Returns an array of conversation objects.

<ResponseField name="id" type="string (UUID)">
  Unique identifier for the conversation.
</ResponseField>

<ResponseField name="business_id" type="string (UUID)">
  The business this conversation belongs to.
</ResponseField>

<ResponseField name="customer_id" type="string (UUID) | null">
  The customer associated with this conversation.
</ResponseField>

<ResponseField name="assignee_id" type="string (UUID) | null">
  The agent this conversation is assigned to, or `null` if unassigned.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the conversation. One of `"open"`, `"pending"`, `"resolved"`, or `"closed"`.
</ResponseField>

<ResponseField name="channel_type" type="string">
  The channel this conversation came through (e.g. `"widget"`, `"email"`, `"whatsapp"`).
</ResponseField>

<ResponseField name="channel_id" type="string (UUID) | null">
  The channel record this conversation is linked to.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  Timestamp when the conversation was created.
</ResponseField>

<ResponseField name="updated_at" type="string (ISO 8601)">
  Timestamp when the conversation was last updated.
</ResponseField>

<ResponseField name="first_response_at" type="string (ISO 8601) | null">
  Timestamp of the first agent response, used for SLA tracking.
</ResponseField>

<ResponseField name="customer" type="object | null">
  Embedded customer object if available.
</ResponseField>

<ResponseField name="messages" type="array">
  Array of messages. May be empty in list responses for performance.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.pingback.live/api/v1/conversations/?status=open&page=1&limit=20" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ status: 'open', page: 1, limit: 20 });
  const response = await fetch(`https://api.pingback.live/api/v1/conversations/?${params}`, {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  });
  const conversations = await response.json();
  ```
</CodeGroup>

### Response example

```json theme={null}
[
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "business_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "customer_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "assignee_id": null,
    "status": "open",
    "channel_type": "widget",
    "channel_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "created_at": "2024-03-01T09:00:00Z",
    "updated_at": "2024-03-01T09:15:00Z",
    "first_response_at": null,
    "customer": {
      "id": 42,
      "business_id": 7,
      "name": "Alex Johnson",
      "email": "alex@example.com",
      "phone": null,
      "external_id": null,
      "created_at": "2024-02-20T08:00:00Z"
    },
    "messages": []
  }
]
```

## Errors

| Status | Meaning                                          |
| ------ | ------------------------------------------------ |
| 401    | Unauthorized — missing or invalid Bearer token   |
| 422    | Validation error — invalid query parameter value |