Skip to content
  • api
  • reference

API Reference

Base URL

Section titled “Base URL”
https://api.chatagent.so/v1

Common headers

Section titled “Common headers”
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Conversations

Section titled “Conversations”

List conversations

Section titled “List conversations”
GET /conversations

Query parameters:

Parameter Type Description
status string Filter by status: active, resolved, archived
platform string Filter by platform: whatsapp, facebook, instagram
limit integer Results per page (default: 20, max: 100)
offset integer Pagination offset
search string Search in contact name or phone

Response:

{
  "data": [
    {
      "id": "conv_abc123",
      "contact": {
        "id": "cnt_123",
        "name": "John Doe",
        "phone": "+1234567890"
      },
      "platform": "whatsapp",
      "status": "active",
      "message_count": 5,
      "last_message": {
        "content": "Thanks for your help!",
        "timestamp": "2026-01-15T10:30:00Z"
      },
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Get conversation

Section titled “Get conversation”
GET /conversations/:id

Send message

Section titled “Send message”
POST /messages

Request body:

{
  "conversation_id": "conv_abc123",
  "content": "Thanks for your order!",
  "type": "text"
}

Contacts

Section titled “Contacts”

List contacts

Section titled “List contacts”
GET /contacts

Get contact

Section titled “Get contact”
GET /contacts/:id

Create contact

Section titled “Create contact”
POST /contacts

Request body:

{
  "name": "Jane Smith",
  "phone": "+0987654321",
  "email": "jane@example.com",
  "tags": ["vip", "new-customer"]
}

Update contact

Section titled “Update contact”
PATCH /contacts/:id

Delete contact

Section titled “Delete contact”
DELETE /contacts/:id

Orders

Section titled “Orders”

List orders

Section titled “List orders”
GET /orders

Get order

Section titled “Get order”
GET /orders/:id

Tags

Section titled “Tags”

List tags

Section titled “List tags”
GET /tags

Add tag to contact

Section titled “Add tag to contact”
POST /contacts/:id/tags

Request body:

{
  "tag": "vip"
}

Remove tag from contact

Section titled “Remove tag from contact”
DELETE /contacts/:id/tags/:tag

Workflows

Section titled “Workflows”

Trigger workflow

Section titled “Trigger workflow”
POST /workflows/:id/trigger

Request body:

{
  "contact_id": "cnt_123",
  "data": {
    "order_id": "ord_456"
  }
}

List workflow runs

Section titled “List workflow runs”
GET /workflows/:id/runs

Errors

Section titled “Errors”
Status Code Description
400 bad_request Invalid request body or parameters
401 unauthorized Missing or invalid API key
403 forbidden Key doesn’t have permission
404 not_found Resource doesn’t exist
429 rate_limited Too many requests
500 server_error Internal error

Error response:

{
  "error": {
    "code": "bad_request",
    "message": "Phone number is required",
    "details": {
      "field": "phone",
      "constraint": "required"
    }
  }
}

Pagination

Section titled “Pagination”

All list endpoints support pagination:

GET /conversations?limit=20&offset=40

Response includes:

{
  "data": [...],
  "total": 150,
  "limit": 20,
  "offset": 40,
  "has_more": true
}

Next steps

Section titled “Next steps”