Skip to main content

API Reference

Chat

Power the chat widget and manage conversations. Uses the site key for authentication.

Get Widget Config

GET /api/v1/chat/config Site Key 60 req/min

Returns the chat widget configuration for the account.

Response

{
  "greeting": "Hi there! How can we help?"
}

Create Conversation

POST /api/v1/chat/conversations Site Key 5 req/min

Creates a new chat conversation with an initial message.

Parameters

Parameter Type Required Description
name string Yes Contact name
email string Yes Valid email address
message string Yes Initial message (max 10,000 characters)
visitor_token string Yes Unique visitor identifier

Success Response (201)

{
  "conversation_token": "abc123...",
  "auto_reply": "Thanks for reaching out! We'll get back to you soon."
}

Error Responses

// 422 Unprocessable Entity
{ "error": "Name, email, message, and visitor_token are required" }
{ "error": "Invalid email address" }
{ "error": "Message is too long (maximum 10000 characters)" }

// 409 Conflict
{ "error": "A conversation with this visitor token already exists" }

Get Messages

GET /api/v1/chat/conversations/:visitor_token/messages Site Key 60 req/min

Returns all messages in a conversation, or only messages after a given timestamp.

Parameters

Parameter Type Required Description
visitor_token string Yes URL parameter — conversation identifier
since string No ISO 8601 datetime — only return messages after this time

Response

[
  {
    "direction": "inbound",
    "body": "Hi, I need help with billing.",
    "timestamp": "2025-01-15T10:30:00Z",
    "author": "Jane Doe"
  },
  {
    "direction": "outbound",
    "body": "Sure! Let me look into that for you.",
    "timestamp": "2025-01-15T10:35:00Z",
    "author": "Support"
  }
]

Send Reply

POST /api/v1/chat/conversations/:visitor_token/messages Site Key 20 req/min

Sends a reply to an existing conversation. Automatically reopens the conversation if it was closed.

Parameters

Parameter Type Required Description
visitor_token string Yes URL parameter — conversation identifier
message string Yes Reply text (max 10,000 characters)

Success Response (201)

{
  "status": "ok"
}

Download File

GET /api/v1/chat/conversations/:visitor_token/files/:activity_id/:id Site Key 60 req/min

Downloads a file attachment from a conversation message.

Parameters

Parameter Type Required Description
visitor_token string Yes URL parameter — conversation identifier
activity_id integer Yes URL parameter — message activity ID
id integer Yes URL parameter — file attachment ID
disposition string No "inline" or "attachment" (defaults to "attachment")

Response

Returns the file binary with appropriate content type headers.