# Conversations API

The Conversations API lets you programmatically access conversation threads, messages, and lead context from your Zipchat chatbot. Use it to sync data into your CRM, build reporting dashboards, or power internal workflows.

### How to Set Up Conversations API

1. In Zipchat, go to **Chat Settings > Integrations**.
2. Enable the **Backend API** integration.
3. Copy your **API Key** and **Chat ID** from the integration card.
4. Use those credentials to call the endpoints below.

<figure><img src="https://2043605213-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvYpZDb6HsnLHFu8ZygCS%2Fuploads%2Fqm8PSrsu4btglkCJrJdu%2Fimage.png?alt=media&#x26;token=b8ced349-10be-4f1b-a229-59cb21cfe5b5" alt=""><figcaption></figcaption></figure>

### Authentication

Send your API key in the Authorization header as a Bearer token:

```http
Authorization: Bearer zc-your_api_key_here
```

Requests with a missing or invalid token return `401 Unauthorized`.

### Base URL

```http
https://app.zipchat.ai/api/integrations/backend_api/v1
```

### Endpoints

#### 1) List Conversations

```http
GET /chats/:chat_id/conversations
```

Returns a paginated list of conversations for the selected chat.

**Query parameters**

<table><thead><tr><th width="223.59765625">Parameter</th><th width="154.12890625">Type</th><th width="101.11328125">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>page</code></td><td>integer</td><td>1</td><td>Conversation page number</td></tr><tr><td><code>per_page</code></td><td>integer</td><td>50</td><td>Conversations per page (max 100)</td></tr><tr><td><code>last_message_at_since</code></td><td>string (ISO 8601)</td><td>—</td><td>Return only conversations updated at or after this timestamp</td></tr></tbody></table>

**Response**

```json
{
  "conversations": [
    {
      "id": 12345,
      "chat_id": 1,
      "created_at": "2026-02-20T10:30:00Z",
      "last_message_at": "2026-02-20T10:45:00Z",
      "channel": "chat",
      "manual_reply_mode": false,
      "share_url": "https://app.zipchat.ai/chats/1/conversations/12345",
      "lead": {
        "id": 100,
        "full_name": "Jane Doe",
        "email": "jane@example.com",
        "phone_number": "+1234567890",
        "email_marketing_consent": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_count": 142,
    "total_pages": 3,
    "has_next_page": true
  }
}
```

lead is null when no lead is attached to a conversation.

***

#### 2) Get Conversation Details (with Messages)

```http
GET /chats/:chat_id/conversations/:id
```

Returns one conversation plus visible messages and message pagination metadata.

**Query parameters**

<table><thead><tr><th width="237.2734375">Parameter</th><th width="163.76953125">Type</th><th width="96.0859375">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>message_page</code></td><td>integer</td><td>1</td><td>Message page number</td></tr><tr><td><code>message_per_page</code></td><td>integer</td><td>100</td><td>Messages per page (max 200)</td></tr><tr><td><code>message_created_at_since</code></td><td>string (ISO 8601)</td><td>—</td><td>Return only messages created at or after this timestamp</td></tr></tbody></table>

**Response**

```json
{
  "conversation": {
    "id": 12345,
    "created_at": "2026-02-20T10:30:00Z",
    "last_message_at": "2026-02-20T10:45:00Z",
    "channel": "chat",
    "manual_reply_mode": false,
    "share_url": "https://app.zipchat.ai/chats/1/conversations/12345",
    "lead": {
      "id": 100,
      "first_name": "Jane",
      "last_name": "Doe",
      "full_name": "Jane Doe",
      "email": "jane@example.com",
      "phone_number": "+1234567890",
      "email_marketing_consent": true,
      "phone_marketing_consent": false,
      "shopify_customer_id": "7890123456",
      "additional_attributes": {},
      "created_at": "2026-02-20T10:31:00Z"
    },
    "messages": [
      {
        "id": 50001,
        "created_at": "2026-02-20T10:30:05Z",
        "role": "user",
        "message": "Do you have this in blue?",
        "count_as_reply": false,
        "manual_reply": false,
        "status": "sent",
        "rate": null,
        "sender_id": null
      }
    ],
    "messages_pagination": {
      "page": 1,
      "per_page": 100,
      "total_count": 1,
      "total_pages": 1,
      "has_next_page": false
    }
  }
}
```

### Rate Limiting

The API is limited to **120 requests per 60-second window** per integration.

Every response includes:

* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset (Unix timestamp)`

Exceeded limits return 429 Too Many Requests.

### Error Codes

<table><thead><tr><th width="240.79296875">Status</th><th>Meaning</th></tr></thead><tbody><tr><td><code>401 Unauthorized</code></td><td>Missing or invalid token</td></tr><tr><td><code>404 Not Found</code></td><td>Conversation not found for this chat</td></tr><tr><td><code>422 Unprocessable Entity</code></td><td>Invalid parameter format (for example, malformed timestamp)</td></tr><tr><td><code>429 Too Many Requests</code></td><td>Rate limit exceeded</td></tr></tbody></table>

### Example Requests

#### Fetch conversations

```bash
curl -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations"
```

#### Poll conversations updated since a timestamp

```bash
curl -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations?last_message_at_since=2026-02-20T09:30:00Z"
```

#### Fetch one conversation

```bash
curl -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345"
```

#### Paginate messages in a conversation

```bash
curl -H "Authorization: Bearer zc-your_api_key" \
  "https://app.zipchat.ai/api/integrations/backend_api/v1/chats/1/conversations/12345?message_page=2&message_per_page=50"
```