Messages

Messages belong to tickets and represent the conversation thread between agents and customers. Each message has a sender type and optional metadata.

The Message object

id string

Unique message identifier (msg_ prefix)

ticketId string

Parent ticket ID (tkt_ prefix)

content string

Message body text

sender string

Who sent the message "agent" | "customer" | "system"

senderName string

Display name of the sender

isInternal boolean

Whether this is an internal note (not visible to customers)

createdAt datetime

When the message was sent

Endpoints

GET List Messages POST Add Message

GET /api/v1/teams/{teamId}/tickets/{ticketId}/messages

List Messages

Try it

Get all messages for a ticket, ordered chronologically.

Path Parameters

ticketId string required

The parent ticket ID (tkt_ prefix)

Code Examples

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/tickets/{ticketId}/messages" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Array of messages

{
  "success": true,
  "data": [
    {
      "id": "msg_a1b2c3d4e5f6",
      "ticketId": "tkt_550e8400e29b41d4a716446655440000",
      "content": "I keep getting \"invalid credentials\" when I try to log in.",
      "sender": "customer",
      "senderName": "Jane Smith",
      "isInternal": false,
      "createdAt": "2025-12-10T14:30:00Z"
    },
    {
      "id": "msg_b2c3d4e5f6a7",
      "ticketId": "tkt_550e8400e29b41d4a716446655440000",
      "content": "I'll look into this for you right away.",
      "sender": "agent",
      "senderName": "Bob (Support)",
      "isInternal": false,
      "createdAt": "2025-12-10T14:35:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:35:00Z"
  }
}

404 Ticket not found

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Ticket not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

POST /api/v1/teams/{teamId}/tickets/{ticketId}/messages

Add Message

Try it

Add a new message to a ticket thread. Fires the `ticket.message_added` webhook event.

Requires a secret API key.

Path Parameters

ticketId string required

The parent ticket ID (tkt_ prefix)

Request Body

content string required

Message body text

sender string

Sender type

Default: agent

senderName string

Display name (optional)