Conversations

Create and manage support conversations programmatically.

POST

/api/v1/conversations/create/Server or Client key

Create a new conversation. The user is looked up by email, or created if they don't exist.

Request Body

Name	Type	Description
`subject`*	string	Conversation subject (max 500 chars)
`user_email`	string	Email of the end user. If omitted, an anonymous user is created.
`description`	string	Initial message or context
`user_first_name`	string	First name (used if user is created)
`user_last_name`	string	Last name (used if user is created)
`priority`	string	low, normal (default), high, or urgent
`channel`	string	Source channel: web, email, api, or callback
`metadata`	object	Arbitrary JSON metadata (e.g., phone number, preferred callback time)

json

// Response 201
{
  "id": "a1b2c3d4-...",
  "number": 42,
  "subject": "Help with order #1234",
  "status": "open",
  "priority": "normal",
  "channel": "web",
  "metadata": {},
  "requester": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "created_at": "2026-02-26T10:00:00Z",
  "updated_at": "2026-02-26T10:00:00Z"
}

GET

/api/v1/conversations/Server or Client key

List conversations for your organization. Supports pagination.

Query Parameters

Name	Type	Description
`user_email`	string	Filter by requester email
`status`	string	Filter by status: open, pending, resolved, closed
`limit`	integer	Page size (default 20, max 100)
`offset`	integer	Pagination offset

GET

/api/v1/conversations/{id}/Server or Client key

Get a single conversation by ID.

GET

/api/v1/conversations/{id}/messages/Server or Client key

List all messages in a conversation. Ordered oldest first.

json

// Response 200
{
  "count": 3,
  "results": [
    {
      "id": "m1-uuid",
      "sender_email": "customer@example.com",
      "body": "I need help with my order",
      "message_type": "reply",
      "created_at": "2026-02-26T10:00:00Z"
    },
    {
      "id": "m2-uuid",
      "sender_email": "agent@yourcompany.com",
      "body": "Sure! Let me look into that.",
      "message_type": "reply",
      "created_at": "2026-02-26T10:05:00Z"
    }
  ]
}

POST

/api/v1/conversations/{id}/messages/create/Server or Client key

Send a message in a conversation. The sender is identified by email.

Request Body

Name	Type	Description
`body`*	string	The message content
`user_email`*	string	Email of the sender

POST

/api/v1/conversations/{id}/resolve/Server key only

Resolve (close) a conversation. Only available with server keys.

json

// Response 200
{
  "id": "a1b2c3d4-...",
  "number": 42,
  "subject": "Help with order #1234",
  "status": "closed",
  ...
}

Loading…

Conversations

Create and manage support conversations programmatically.

POST

/api/v1/conversations/create/Server or Client key

Create a new conversation. The user is looked up by email, or created if they don't exist.

Request Body

Name	Type	Description
`subject`*	string	Conversation subject (max 500 chars)
`user_email`	string	Email of the end user. If omitted, an anonymous user is created.
`description`	string	Initial message or context
`user_first_name`	string	First name (used if user is created)
`user_last_name`	string	Last name (used if user is created)
`priority`	string	low, normal (default), high, or urgent
`channel`	string	Source channel: web, email, api, or callback
`metadata`	object	Arbitrary JSON metadata (e.g., phone number, preferred callback time)

json

// Response 201
{
  "id": "a1b2c3d4-...",
  "number": 42,
  "subject": "Help with order #1234",
  "status": "open",
  "priority": "normal",
  "channel": "web",
  "metadata": {},
  "requester": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "created_at": "2026-02-26T10:00:00Z",
  "updated_at": "2026-02-26T10:00:00Z"
}

GET

/api/v1/conversations/Server or Client key

List conversations for your organization. Supports pagination.

Query Parameters

Name	Type	Description
`user_email`	string	Filter by requester email
`status`	string	Filter by status: open, pending, resolved, closed
`limit`	integer	Page size (default 20, max 100)
`offset`	integer	Pagination offset

GET

/api/v1/conversations/{id}/Server or Client key

Get a single conversation by ID.

GET

/api/v1/conversations/{id}/messages/Server or Client key

List all messages in a conversation. Ordered oldest first.

json

// Response 200
{
  "count": 3,
  "results": [
    {
      "id": "m1-uuid",
      "sender_email": "customer@example.com",
      "body": "I need help with my order",
      "message_type": "reply",
      "created_at": "2026-02-26T10:00:00Z"
    },
    {
      "id": "m2-uuid",
      "sender_email": "agent@yourcompany.com",
      "body": "Sure! Let me look into that.",
      "message_type": "reply",
      "created_at": "2026-02-26T10:05:00Z"
    }
  ]
}

POST

/api/v1/conversations/{id}/messages/create/Server or Client key

Send a message in a conversation. The sender is identified by email.

Request Body

Name	Type	Description
`body`*	string	The message content
`user_email`*	string	Email of the sender

POST

/api/v1/conversations/{id}/resolve/Server key only

Resolve (close) a conversation. Only available with server keys.

json

// Response 200
{
  "id": "a1b2c3d4-...",
  "number": 42,
  "subject": "Help with order #1234",
  "status": "closed",
  ...
}