Chat API reference

Authentication

Every request is authenticated with your workspace API key, sent in the X-API-Key header (or an api_key parameter). Keys look like ck_live_.... Treat the key like a password - anyone holding it can send messages billed to your workspace. Rotate it any time from Settings -> API access; the previous key stops working immediately.

Send a message

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

Parameters:

• message (string) - the visitor message. Required unless files are attached.
• ticket_id (string, optional) - continue an existing conversation. Omit to start a new one.
• visitor_email / visitor_name (string, optional) - attach contact details to the ticket.
• files (multipart, optional) - visitor attachments. Requires a plan with file uploads.

Response

The call returns 202 Accepted as soon as the message is stored; the AI reply is generated asynchronously.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

Pass data.ticket_id back as ticket_id on the next call to keep the conversation going. To receive the AI reply, subscribe over WebSocket (ActionCable) to the channel keyed by data.id - the same visitor hash the embedded widget uses.

Read conversations

Pull tickets and their messages with the same X-API-Key. Every read endpoint is scoped to your workspace and available on the Business plan.

• GET /api/v1/chat/tickets - list tickets, newest first. Query params: status, limit (max 100), offset. Returns tickets and pagination.
• GET /api/v1/chat/tickets/:id - a single ticket.
• GET /api/v1/chat/tickets/:id/messages - a ticket's messages in order, each with role, content and attachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

Rate limits & quota

Requests are throttled to roughly 20 per minute per key (and per IP). Each generated reply also draws from your plan's monthly message allowance; once it is exhausted the endpoint returns a 200 with data.limit_reached: true instead of generating a reply.

Errors

• 401 - no API key supplied.
• 404 - the key does not match any workspace (e.g. after rotation).
• 403 plan_upgrade_required - the workspace is not on the Business plan.
• 403 - the subscription is inactive, or the request came from a domain not allowed by the widget's settings.
• 422 - the message is missing (and no files were attached).