Messages represent individual replies, responses, and internal notes within a ticket conversation.
Note: The Messages API uses session-based (JWT) authentication rather than API key authentication. These endpoints are available at /helpdesk/api/messages and require a valid session token.
The message object
| Attribute | Type | Description |
|---|
id | string | Unique identifier |
ticketId | string | ID of the parent ticket |
type | string | request, response, or note |
content | string | HTML content of the message |
textContent | string | Plain-text content (optional) |
authorId | string | ID of the user who created the message |
attachments | array | File attachments (optional) |
ccs | array | CC recipients (optional) |
createdAt | timestamp | Creation time (UTC) |
updatedAt | timestamp | Last update time (UTC) |
Message types
| Type | Description |
|---|
request | Inbound message from the customer |
response | Outbound reply from an agent (sends email by default) |
note | Internal note visible only to agents |
List messages
GET /helpdesk/api/messages?ticket_id=tkt_abc123
Returns a paginated list of messages for a given ticket. Requires the viewer role or higher.
Query parameters
| Parameter | Type | Required | Description |
|---|
ticket_id | string | yes | The ticket to list messages for |
page | integer | no | Page number (default: 1) |
limit | integer | no | Results per page, 1-100 (default: 50) |
sort_order | string | no | asc or desc (default: asc) |
Retrieve a message
GET /helpdesk/api/messages/:messageId
Requires the viewer role or higher.
Create a message
POST /helpdesk/api/messages
Creates a reply, response, or internal note on a ticket. Requires the agent role or higher.
Request body
| Field | Type | Required | Description |
|---|
ticket_id | string | yes | ID of the parent ticket |
type | string | yes | request, response, or note |
content | string | yes | HTML content |
text_content | string | no | Plain-text fallback |
recipients | array | no | Override recipients for forwards |
ccs | array | no | CC recipients ({ email, name }) |
attachments | array | no | Attachment references ({ token, name, size }) |
send_email | boolean | no | Send email for response type (default: true) |
is_forward | boolean | no | Treat as a forward |
ticket_update | object | no | Atomically update ticket fields with the message |
ticket_update fields
| Field | Type | Description |
|---|
status | string | New ticket status |
priority | string | low, normal, high, urgent |
type | string | question, incident, problem, task |
Error codes
| Code | Status | Description |
|---|
TICKET_CLOSED | 403 | Cannot add messages to closed tickets |
CLOSED_STATUS_SYSTEM_ONLY | 403 | Closed status can only be set by system automations |