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.

Authentication

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

Authorization: Bearer zc-your_api_key_here

Requests with a missing or invalid token return 401 Unauthorized.

Base URL

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

Endpoints

1) List Conversations

GET /chats/:chat_id/conversations

Returns a paginated list of conversations for the selected chat.

Query parameters

Parameter	Type	Default	Description
page	integer	1	Conversation page number
per_page	integer	50	Conversations per page (max 100)
last_message_at_since	string (ISO 8601)	—	Return only conversations updated at or after this timestamp

Response

{
  "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": "[email protected]",
        "phone_number": "[phone]",
        "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)

GET /chats/:chat_id/conversations/:id

Returns one conversation plus visible messages and message pagination metadata.

Query parameters

Parameter	Type	Default	Description
message_page	integer	1	Message page number
message_per_page	integer	100	Messages per page (max 200)
message_created_at_since	string (ISO 8601)	—	Return only messages created at or after this timestamp

Response

{
  "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": "[email protected]",
      "phone_number": "[phone]",
      "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

Status	Meaning
401 Unauthorized	Missing or invalid token
404 Not Found	Conversation not found for this chat
422 Unprocessable Entity	Invalid parameter format (for example, malformed timestamp)
429 Too Many Requests	Rate limit exceeded

Example Requests

Fetch conversations

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

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

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

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"