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

# List Conversations

> List the WhatsApp conversations of a channel that started in a date range

Returns the conversations of a WhatsApp channel that started between two dates, newest first, one page at a time. They are the same conversations as **Reports → Sessions** in the app.

A thread is the whole chat with a contact on a channel and never ends. A conversation is one stretch of that thread: it opens with new activity and closes after a period without messages, so one thread has many conversations. To read the messages of a conversation, call [List Thread Messages](https://docs.contactship.ai/api-reference/endpoint/get-thread-messages.md) with its `thread_id` and `session_id` set to its `id`.

> [!NOTE]
>
> Only WhatsApp (`WABA`) channels have conversations. For any other channel the list is empty.

## Headers

**x-api-key** `string` *required*

Your API key for authentication. An organization key lists every conversation of the channel. A personal key needs the `messages.read` permission and the channel inside its role's channels; it lists only the conversations of threads its user can see in the inbox.

## Query Parameters

**channel\_id** `string` *required*

ID of the WhatsApp channel, from [List Channels](https://docs.contactship.ai/api-reference/endpoint/get-channels.md).

**start\_date** `string` *required*

First day of the range, `YYYY-MM-DD`. A conversation is in the range when it started in it.

**end\_date** `string` *required*

Last day of the range, included, `YYYY-MM-DD`. It cannot be before `start_date`.

**timezone** `string` (default: UTC)

IANA time zone the two days are read in, e.g. `America/Bogota`. An unknown zone is read as UTC.

**limit** `number` (default: 50)

Conversations per page, from 1 to 100.

**offset** `number` (default: 0)

Number of conversations to skip, up to 10000.

## Response

**data** `array`

Conversations of the page, newest first.

**Conversation object**

**id** `string`

Unique identifier of the conversation (UUID). Pass it as `session_id` to [List Thread Messages](https://docs.contactship.ai/api-reference/endpoint/get-thread-messages.md).

**thread\_id** `string`

UUID of the thread the conversation belongs to.

**channel\_id** `string`

ID of the channel.

**channel\_name** `string`

Display name of the channel.

**contact\_id** `string`

UUID of the contact.

**contact\_name** `string`

Full name of the contact.

**contact\_phone** `string`

Phone number of the contact.

**status** `string`

`open` while the conversation is active, `closed` once it ended.

**started\_at** `string`

When the conversation started (ISO 8601).

**ended\_at** `string`

When it closed (ISO 8601). `null` while it is open.

**message\_count** `number`

Messages in the conversation.

**user\_message\_count** `number`

Messages the contact sent.

**first\_response\_at** `string`

When the first reply to the contact was sent, by the AI agent or a person (ISO 8601), or `null`.

**is\_returning** `boolean`

`true` when the contact had an earlier conversation on this channel.

**handled\_by** `string`

Who answered: `ai`, `human`, `mixed` or `none`. `null` while the conversation is open, and for conversations that closed before September 7, 2026.

**escalated\_at** `string`

When the conversation was handed from the AI agent to a person (ISO 8601), or `null`.

**escalated\_by\_type** `string`

Who made the handoff: `agent` (the AI agent escalated), `user` (a person on your team took the conversation over) or `system` (a rule or automation). `null` when there was none.

**analyzed\_at** `string`

When the conversation was analyzed (ISO 8601), or `null`.

**analysis** `object`

The analysis written when the conversation closes, only on channels with conversation analysis turned on; `null` otherwise.

**Analysis object**

**session\_summary** `string`

Summary of the conversation.

**user\_sentiment** `string`

Sentiment of the contact: `Positive`, `Neutral` or `Negative`.

**session\_successful** `boolean`

Whether the conversation reached its goal.

**custom\_analysis\_data** `object`

The custom fields set up for the channel's analysis.

**pagination** `object`

**Pagination object**

**page** `number`

Page number, from 1.

**total\_rows** `number`

Conversations in the range.

**total\_pages** `number`

Pages at the requested `limit`.

The conversation does not carry who it was assigned to: read the thread's `assignee` with [Get Thread](https://docs.contactship.ai/api-reference/endpoint/get-thread.md), or the `sender_id` of each message.

## Error Codes

* `400 Bad Request` — A parameter is missing or invalid, or `end_date` is before `start_date`
* `401 Unauthorized` — Invalid or missing API key
* `403 Forbidden` — The personal key lacks `messages.read`, or the channel is not among its role's channels
* `429 Too Many Requests` — Rate limit exceeded, see [Rate limits](https://docs.contactship.ai/api-reference/rate-limits.md)
* `500 Internal Server Error` — Server-side error

## Code Examples

```bash cURL theme={null}
curl -X GET "https://api.contactship.ai/v1/conversations?channel_id=chn_w4b4e5x4mp1e0000000000&start_date=2026-11-01&end_date=2026-11-15&timezone=America/Bogota&limit=100" \
  -H "x-api-key: your-api-key"
```

```javascript JavaScript theme={null}
const params = new URLSearchParams({
  channel_id: 'chn_w4b4e5x4mp1e0000000000',
  start_date: '2026-11-01',
  end_date: '2026-11-15',
  timezone: 'America/Bogota',
  limit: '100',
});
const conversations = [];
for (let offset = 0; ; offset += 100) {
  params.set('offset', String(offset));
  const response = await fetch(`https://api.contactship.ai/v1/conversations?${params}`, {
    headers: { 'x-api-key': 'your-api-key' },
  });
  const { data, pagination } = await response.json();
  conversations.push(...data);
  if (offset + 100 >= pagination.total_rows) break;
}
console.log(`${conversations.length} conversations`);
```

```python Python theme={null}
import requests

params = {
    'channel_id': 'chn_w4b4e5x4mp1e0000000000',
    'start_date': '2026-11-01',
    'end_date': '2026-11-15',
    'timezone': 'America/Bogota',
    'limit': 100,
    'offset': 0,
}
conversations = []
while True:
    page = requests.get(
        'https://api.contactship.ai/v1/conversations',
        headers={'x-api-key': 'your-api-key'},
        params=params,
    ).json()
    conversations += page['data']
    params['offset'] += 100
    if params['offset'] >= page['pagination']['total_rows']:
        break
print(len(conversations), 'conversations')
```

```json Example Response theme={null}
{
  "statusCode": 200,
  "data": [
    {
      "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "thread_id": "thr-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "channel_id": "chn_w4b4e5x4mp1e0000000000",
      "channel_name": "WhatsApp Business",
      "contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "contact_name": "Ana Gómez",
      "contact_phone": "+573001234567",
      "status": "closed",
      "started_at": "2026-11-14T15:03:26Z",
      "ended_at": "2026-11-14T16:10:02Z",
      "message_count": 12,
      "user_message_count": 5,
      "first_response_at": "2026-11-14T15:03:41Z",
      "is_returning": true,
      "handled_by": "mixed",
      "escalated_at": "2026-11-14T15:20:00Z",
      "escalated_by_type": "user",
      "analyzed_at": "2026-11-14T16:11:30Z",
      "analysis": {
        "session_summary": "The contact asked to reschedule a delivery and was handed to an agent, who confirmed the new date.",
        "user_sentiment": "Positive",
        "session_successful": true,
        "custom_analysis_data": {}
      }
    }
  ],
  "pagination": {
    "page": 1,
    "total_rows": 53,
    "total_pages": 2
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.