Messages

Send, list, edit, and delete messages with role-based visibility filtering.

Messages are the content exchanged between participants in a thread. Each message carries a visibility array that determines which participant roles can see it.

Send a Message

POST /api/v1/threads/:threadId/messages

{
  "senderExternalId": "usr-abc",
  "senderRole": "GUEST",
  "content": "What time can I check in?",
  "visibility": ["ALL"]
}

If visibility is omitted, the channel's defaultVisibility is used.

Visibility examples

Visibility	Who sees it
["ALL"]	Every participant
["HOST", "PLATFORM"]	Host and platform only (guest excluded)
["GUEST", "HOST"]	Guest and host only (platform excluded)
["PLATFORM"]	Internal note -- only platform admin

The sender's role is always implicitly included in visibility.

List Messages

GET /api/v1/threads/:threadId/messages

Required header: X-Participant-Role -- determines which messages are returned based on visibility filtering.

# Guest sees only messages where visibility includes GUEST or ALL
curl -H "x-participant-role: GUEST" /api/v1/threads/th-001/messages

# Host sees messages where visibility includes HOST or ALL
curl -H "x-participant-role: HOST" /api/v1/threads/th-001/messages

# Platform sees everything
curl -H "x-participant-role: PLATFORM" /api/v1/threads/th-001/messages

Supports page and limit query parameters.

Send a System Message

POST /api/v1/threads/:threadId/messages/system

{
  "content": "Guest has checked in.",
  "visibility": ["ALL"]
}

System messages have no sender and are displayed differently in the UI (centered, muted styling). Requires threads:admin scope.

Edit a Message

PATCH /api/v1/threads/messages/:messageId

{ "content": "Updated content" }

Sets editedAt timestamp. Pass X-Participant-Role and X-Participant-External-Id headers.

Delete a Message

DELETE /api/v1/threads/messages/:messageId

Soft-deletes the message (sets deletedAt). The message is excluded from list responses but preserved in the audit trail.