Channels API

Manage Telegram and Discord channel integrations.

Create Channel

POST /v1/channels

Request:

{
  "type": "telegram",
  "bot_token_ref": "secret_ref_id",
  "config": {}
}

Field	Type	Required	Description
type	string	Yes	telegram or discord
bot_token_ref	string	Yes	Reference to the bot token in the vault
config	object	No	Channel-specific configuration

Response:

{
  "id": "ch_abc123",
  "type": "telegram",
  "status": "active",
  "created_at": "2025-01-15T10:00:00Z"
}

List Channels

GET /v1/channels

Response:

{
  "channels": [
    {
      "id": "ch_abc123",
      "type": "telegram",
      "status": "active",
      "created_at": "2025-01-15T10:00:00Z"
    },
    {
      "id": "ch_def456",
      "type": "discord",
      "status": "active",
      "created_at": "2025-01-16T14:00:00Z"
    }
  ]
}

Pair Chat to Agent

Bind an external chat (Telegram chat ID, Discord channel ID) to a specific agent.

POST /v1/channels/pair

Request (direct pairing):

{
  "agent_id": "agent_abc123",
  "channel_id": "ch_abc123",
  "external_chat_id": "123456789"
}

Request (pairing code):

{
  "pairing_code": "123456"
}

Response:

{
  "binding_id": "bind_abc123",
  "agent_id": "agent_abc123",
  "channel_id": "ch_abc123",
  "external_chat_id": "123456789"
}

Pairing Codes

Pairing codes are generated when a user sends /start to a Telegram bot. The code is stored in the channel_pairing_codes table and can be used to complete pairing via the API or CLI.

Delete Channel

DELETE /v1/channels/{id}

Response:

{
  "id": "ch_abc123",
  "status": "deleted"
}

Channel Bindings

The channel_bindings table tracks which agent handles messages from which external chat:

Field	Description
agent_id	The agent receiving messages
channel_id	The channel (Telegram/Discord instance)
external_chat_id	The platform-specific chat identifier

One agent can be bound to multiple chats, and one channel can serve multiple agents.

Required Scopes

Endpoint	Scope
POST /v1/channels	channels:write
GET /v1/channels	channels:read
POST /v1/channels/pair	channels:write
DELETE /v1/channels/{id}	channels:write