Conversations

List Conversations

Retrieve all conversations (customers) with their last message, unread counts, and channel info.

GET /api/v1/public/conversations

Query Parameters

Parameter	Type	Required	Description
limit	number	no	Number of conversations to return (1-200, default 50)
cursor	string	no	Customer ID for pagination (from next_cursor in previous response)
channel	string	no	Filter by channel: "whatsapp", "instagram", or "messenger"

Example Request

cURL

curl -X GET "https://chat.api.co.id/api/v1/public/conversations?limit=50&channel=whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch("https://chat.api.co.id/api/v1/public/conversations?limit=50", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});

const { data, pagination } = await response.json();

Python

import requests

response = requests.get(
    "https://chat.api.co.id/api/v1/public/conversations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 50, "channel": "whatsapp"}
)

result = response.json()
conversations = result["data"]
pagination = result["pagination"]

Response

{
  "success": true,
  "data": [
    {
      "customer_id": "clxxx1234567890",
      "phone_number": "628123456789",
      "name": "John Doe",
      "email": "[email protected]",
      "instagram_username": null,
      "tags": ["vip", "loyal"],
      "is_window_active": true,
      "window_expires_at": "2026-01-08T10:30:00.000Z",
      "unread_count": 3,
      "whatsapp_phone_number": {
        "id": "clyyy9876543210",
        "display_phone_number": "+62 812-3456-7890",
        "verified_name": "My Business"
      },
      "instagram": null,
      "messenger": null,
      "last_message": {
        "id": "msg_xyz789",
        "content": "Hello, I need help!",
        "message_type": "TEXT",
        "direction": "INBOUND",
        "status": "DELIVERED",
        "timestamp": "2026-01-07T10:30:00.000Z"
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-07T10:30:00.000Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "clxxx1234567890",
    "limit": 50
  }
}

info

Use next_cursor from the pagination object as the cursor query parameter to fetch the next page.

Get Messages

Retrieve message history for a specific conversation/customer.

GET /api/v1/public/conversations/:customerId/messages

URL Parameters

Parameter	Type	Required	Description
customerId	string	yes	Customer ID (CUID), phone number, or Instagram username

Query Parameters

Parameter	Type	Required	Description
limit	number	no	Number of messages to return (1-200, default 50)
cursor	string	no	ISO date string for pagination (from next_cursor in previous response)
direction	string	no	Filter by direction: "inbound" or "outbound"

Example Request

cURL (by phone)

curl -X GET "https://chat.api.co.id/api/v1/public/conversations/628123456789/messages?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

cURL (by ID)

curl -X GET "https://chat.api.co.id/api/v1/public/conversations/clxxx1234567890/messages?limit=50&direction=inbound" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const customerId = "628123456789"; // or customer CUID
const response = await fetch(
  `https://chat.api.co.id/api/v1/public/conversations/${customerId}/messages?limit=50`,
  {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  }
);

const { data, pagination } = await response.json();
const { customer, messages } = data;

Python

import requests

customer_id = "628123456789"  # or customer CUID
response = requests.get(
    f"https://chat.api.co.id/api/v1/public/conversations/{customer_id}/messages",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 50}
)

result = response.json()
messages = result["data"]["messages"]

Response

{
  "success": true,
  "data": {
    "customer": {
      "id": "clxxx1234567890",
      "phone_number": "628123456789",
      "name": "John Doe",
      "instagram_username": null
    },
    "messages": [
      {
        "id": "msg_abc123",
        "message_type": "TEXT",
        "direction": "INBOUND",
        "content": "Hello, I need help!",
        "media_url": null,
        "status": "READ",
        "timestamp": "2026-01-07T10:30:00.000Z",
        "source": "WHATSAPP_APP",
        "wam_id": "wamid.xxx",
        "whatsapp_phone_number_id": "clyyy9876543210",
        "error": null
      },
      {
        "id": "msg_def456",
        "message_type": "TEXT",
        "direction": "OUTBOUND",
        "content": "Hi! How can I help you?",
        "media_url": null,
        "status": "DELIVERED",
        "timestamp": "2026-01-07T10:31:00.000Z",
        "source": "API",
        "wam_id": "wamid.yyy",
        "whatsapp_phone_number_id": "clyyy9876543210",
        "error": null
      }
    ]
  },
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "limit": 50
  }
}

info

Messages are returned in reverse chronological order (newest first). Use the cursor parameter with the next_cursor value to load older messages.

Try it out

tip

Press Try it and paste your API key (kc_live_...) into the API key (Bearer) field. Get the key from API Keys. Requests run against your live account, so endpoints that send, create, or delete act on real data.

• GET/api/v1/public/conversationsList Conversations
• GET/api/v1/public/conversations/{customerId}/messagesGet Messages