Support

Customer-facing support / chat-widget API. Each session has exactly one widget conversation; the server resolves it from the session identity, so callers never have to track a `conversation_id`.

POST /api/v1/support/conversation

Find or create the customer’s widget conversation. Returns the conversation metadata plus the most recent 50 messages.

Request

cURL

curl -X POST https://api.cimplify.io/api/v1/support/conversation \
  -H "X-Public-Key: pk_test_your_publishable_key"

Response

{
  "success": true,
  "data": {
    "conversation": {
      "id": "thr_01H…",
      "status": "open",
      "ai_enabled": true,
      "message_count": 4,
      "created_at": "2026-05-07T16:21:00Z",
      "last_message_at": "2026-05-07T16:42:18Z"
    },
    "messages": [
      {
        "id": "msg_01H…",
        "sender_type": "customer",
        "content": "Hi, where is my order?",
        "content_type": "text",
        "attachments": [],
        "metadata": {},
        "created_at": "2026-05-07T16:21:00Z"
      }
    ]
  }
}

POST /api/v1/support/conversation/messages

Send a message as the customer. The server resolves the thread by widget identity from the session, so the body is just { content, client_id? }; no thread / conversation ID required.

Body

Field	Type	Description
`content`	string	Message text. 1–4000 chars after trim.
`client_id`	string	Widget-supplied idempotency key. Replaying it returns 409.

Request

cURL

curl -X POST https://api.cimplify.io/api/v1/support/conversation/messages \
  -H "X-Public-Key: pk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Has my order shipped yet?",
    "client_id": "msg-client-01H…"
  }'

Response

{
  "success": true,
  "data": {
    "id": "msg_01H…",
    "sender_type": "customer",
    "content": "Has my order shipped yet?",
    "content_type": "text",
    "attachments": [],
    "metadata": {},
    "created_at": "2026-05-07T16:42:18Z"
  }
}

Errors

400 BAD_REQUEST: empty content after trimming, or longer than 4000 chars.
409 CONFLICT: same client_id already accepted on this thread.

GET /api/v1/support/conversation/messages

Poll for messages. Use the after ISO timestamp as a cursor; limit caps at 100 (default 50). Returns messages in ascending timestamp order.

Query parameters

Param	Description
`after`	ISO 8601 timestamp; only newer messages are returned.
`limit`	1–100, default 50.

cURL

curl "https://api.cimplify.io/api/v1/support/conversation/messages?after=2026-05-07T16:42:00Z&limit=50" \
  -H "X-Public-Key: pk_test_your_publishable_key"

GET /api/v1/support/conversation/ws

WebSocket upgrade for real-time messages. The server sends a resync frame on connect with latest_message_at; clients compare against their local high-water mark and call GET /messages?after=… if behind. Pings are exchanged every 30 seconds; the server closes idle clients after 90 seconds without a pong.

Auth Authenticated customers get a stable thread keyed to their account, not just the anonymous session.
Uploads Attach files to messages by uploading first, then referencing the URL.

Support

On this page