Channels

Configure entity type definitions with participant roles, visibility rules, and lifecycle.

Channels are the foundation of contextual messaging. Each channel defines an entity type and its conversation rules. A property management platform might create a booking channel; a healthcare platform might create an appointment channel.

Create a Channel

POST /api/v1/threads/channels

{
  "slug": "booking",
  "displayName": "Booking Conversations",
  "entityType": "BOOKING",
  "participantRoles": ["GUEST", "HOST", "PLATFORM"],
  "defaultVisibility": ["ALL"],
  "lifecycleRules": {
    "autoClose": {
      "onEntityStatus": ["CHECKED_OUT", "CANCELLED"]
    },
    "autoArchive": {
      "afterClosedDays": 90
    },
    "systemMessages": {
      "onThreadCreated": "A new conversation has been started.",
      "onThreadClosed": "This conversation has been closed ({closedReason})."
    }
  }
}

Response (201):

{
  "success": true,
  "data": {
    "id": "ch_abc123",
    "organizationId": "org_001",
    "slug": "booking",
    "displayName": "Booking Conversations",
    "entityType": "BOOKING",
    "participantRoles": ["GUEST", "HOST", "PLATFORM"],
    "defaultVisibility": ["ALL"],
    "lifecycleRules": { ... },
    "isActive": true,
    "createdAt": "2026-04-12T00:00:00.000Z"
  }
}

List Channels

GET /api/v1/threads/channels

Returns all channels for your organization.

Update a Channel

PATCH /api/v1/threads/channels/:id

Update lifecycle rules, display name, or active status. Changes apply to new threads; existing threads retain their original channel config.

Lifecycle Rules

Rule	Description
autoClose.onEntityStatus	Array of status strings that trigger thread closure
autoClose.afterInactivityDays	Close thread after N days with no messages
autoArchive.afterClosedDays	Archive thread N days after closure
retention.deleteAfterDays	Hard-delete thread data after N days
systemMessages.onThreadCreated	Auto-post system message when thread opens
systemMessages.onThreadClosed	Auto-post system message when thread closes (supports {closedReason} placeholder)