Skip to Content
GuidesChannels

Channels

Channels bind a platform, credentials, and target chat to a stable channel_id.

Register channels with POST /v1/channels/new (/new creates a durable resource). Outbound chat on MESSAGE channels uses POST /v1/messages/send, not /new.

Create

POST /v1/channels/new

{
  "channel_id": "ops-slack",
  "platform": "slack",
  "target_chat_id": "C01234567",
  "credentials": {
    "bot_token": "xoxb-...",
    "signing_secret": "..."
  },
  "callback_url": "https://agent.example/on_message",
  "channel_type": "MESSAGE"
}
FieldTypeNotes
channel_idstringRequired, stable slug
platformenumtelegram | slack | … — immutable after creation
target_chat_idstringPlatform-specific chat / channel / space / PSID
credentialsobjectPlatform-specific strings
callback_urlstringRequired for MESSAGE
channel_typeenumMESSAGE (default) or PROMPT — immutable after creation

Returns 409 if channel_id already exists. To reuse an id after DELETE /v1/channels/{id}, call PATCH /v1/channels/{id} (not POST).

Platform webhooks vs callback_url

Two different URLs are involved for MESSAGE channels on webhook-based platforms:

URLDirectionPurpose
{PUBLIC_WEBHOOK_URL}/webhooks/{organization_id}/{platform}/{channel_id}Platform → GreenlightChat platform delivers inbound events to Greenlight
callback_url on the channelGreenlight → your agent/automationGreenlight forwards inbound chat as message.created

PROMPT channels usually only need the Agent API (POST /v1/prompts/new). Telegram can use long polling locally without a public platform webhook.

Update

PATCH /v1/channels/{id}

Update mutable fields: target_chat_id, credentials, callback_url. Also reactivates a channel after DELETE. platform and channel_type cannot be changed — create a new channel with a new channel_id instead.

Routing rules

  • PROMPT — many agents or workflows can POST /v1/prompts/new to the same channel_id. Answers go to each prompt’s callback_url, not a shared channel callback.
  • MESSAGE — inbound chat goes to the single callback_url set on the channel. There is no fan-out to multiple webhooks.
  • Prefer one active channel_id per platform + target chat + credentials. If two active rows share that binding, inbound resolution is nondeterministic.

See Features & benefits for diagrams and when to choose each mode.

List and delete

GET /v1/channels?platform=slack&channel_type=MESSAGE&limit=50
DELETE /v1/channels/{id}

Both require X-API-Key when auth is enabled.

Send chat text (MESSAGE channels)

POST /v1/messages/send

Use /send to deliver plain chat text on a registered MESSAGE channel (not a prompt card). See Messages for list, get, and send API details.

Platform credentials

See the Platforms section for per-platform credential tables and portal setup.

Automation platformsMessages