Threads

Create and manage entity-scoped conversation threads with participants.

A thread is a conversation tied to a single business entity. Create a thread when the entity is created (e.g., booking confirmed), and the thread follows the entity's lifecycle.

Create a Thread

POST /api/v1/threads

{
  "channelSlug": "booking",
  "entityId": "BK-2026-00451",
  "subject": "Booking BK-2026-00451 — Ocean View Suite",
  "metadata": {
    "propertyId": "prop-001",
    "checkInDate": "2026-05-01"
  },
  "participants": [
    { "role": "GUEST", "externalId": "usr-abc", "displayName": "Ade Bakare" },
    { "role": "HOST", "externalId": "ptn-xyz", "displayName": "Bimpe Adeyemi" },
    { "role": "PLATFORM", "externalId": "system", "displayName": "Support" }
  ]
}

The entityId is your application's identifier for the entity. Combined with the channel, it forms a unique key -- one thread per entity per channel.

List Threads

GET /api/v1/threads?channelSlug=booking&status=OPEN

Filter by channelSlug, entityId, status, participantExternalId, or participantRole.

Get Thread Detail

GET /api/v1/threads/:id

Returns the thread with all participants and channel info.

Close a Thread

POST /api/v1/threads/:id/close

{ "reason": "CHECKED_OUT" }

Pass X-Participant-Role and X-Participant-External-Id headers to record who closed it.

Reopen a Thread

POST /api/v1/threads/:id/reopen

Entity Event (Lifecycle)

Forward entity status changes to trigger lifecycle rules:

POST /api/v1/threads/entity-event

{
  "channelSlug": "booking",
  "entityId": "BK-2026-00451",
  "event": "STATUS_CHANGED",
  "newStatus": "CHECKED_OUT"
}

If the channel's autoClose.onEntityStatus includes CHECKED_OUT, the thread closes automatically with a system message.

Participants

Add a participant

POST /api/v1/threads/:id/participants

{ "role": "AGENT", "externalId": "agt-001", "displayName": "Travel Agent" }

Remove a participant

DELETE /api/v1/threads/:id/participants/:participantId

Update a participant

PATCH /api/v1/threads/:id/participants/:participantId

{ "displayName": "Updated Name", "isMuted": true }