Channels API: Connect Agents to IM Platforms in Octop#

Use the Channels API to programmatically manage which messaging platforms connect to each agent. Each channel links an agent to an external messaging service — such as Feishu, WeCom, DingTalk, or Telegram — using platform-specific credentials stored in the channel's config object. All endpoints require owner-level access to the parent agent.

#Base path

/api/agents/{agent_id}/channels

#Endpoints

#Create a channel

Provide a kind, a name, and a platform-specific config object.

curl -X POST http://127.0.0.1:8088/api/agents/main/channels \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "feishu",
    "name": "Feishu Bot",
    "config": {
      "app_id": "cli_...",
      "app_secret": "..."
    }
  }'

curl -X POST http://127.0.0.1:8088/api/agents/main/channels \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "telegram",
    "name": "Telegram Bot",
    "config": {
      "token": "your-bot-token"
    }
  }'

A successful request returns 201 Created with the new channel row, including its assigned id (used as {cid} in subsequent calls).

Put display options on config. These match Message display in the channel drawer:

#Supported kinds

For kind: "qq", config typically includes app_id, secret (or client_secret), optional c2c_streaming (default true when you save from the web UI), and optional group_context (visibility, activation, history, history_limit).

#QQ QR bind

Generate a QR session, then poll until the mobile QQ scan succeeds:

curl -X POST http://127.0.0.1:8088/api/agents/main/channels/qq/qrcode/generate \
  -H 'Authorization: Bearer $TOKEN'

curl -X POST http://127.0.0.1:8088/api/agents/main/channels/qq/qrcode/poll \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"qrcode_token": "..."}'

On success the poll response includes app_id and secret you can persist with POST / PATCH on the channel.

#DingTalk QR registration

DingTalk can create and enable the channel directly from a QR authorization flow. Generate a registration session, show qrcode_url to the user, then poll with registration_id until the result is success, waiting, expired, or failed.

curl -X POST http://127.0.0.1:8088/api/agents/main/channels/dingtalk/qrcode/generate \
  -H 'Authorization: Bearer $TOKEN'

{
  "registration_id": "...",
  "qrcode_url": "https://...",
  "user_code": "ABCD-EFGH",
  "expires_in": 600,
  "interval": 5
}

curl -X POST http://127.0.0.1:8088/api/agents/main/channels/dingtalk/qrcode/poll \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"registration_id": "..."}'

On success, Octop returns {"status":"success","channel_id":"..."} and stores an enabled DingTalk channel with live progress mode and hidden thinking/tool hints.

#Test a channel

After creating a channel, verify its credentials are valid and the platform is reachable by calling the test endpoint. Octop instantiates the channel handler, starts it, and stops it, returning a simple ok flag.

curl -X POST http://127.0.0.1:8088/api/agents/main/channels/ch_abc/test \
  -H 'Authorization: Bearer $TOKEN'

{"ok": true}

{"ok": false, "error": "Invalid bot token"}

#Update a channel

Send a PATCH with only the fields you want to change — name, config, or both. The response contains the updated channel row.

curl -X PATCH http://127.0.0.1:8088/api/agents/main/channels/ch_abc \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Production Feishu Bot"}'

#Delete a channel

Deleting a channel disconnects it from the agent immediately and returns 204 No Content.

curl -X DELETE http://127.0.0.1:8088/api/agents/main/channels/ch_abc \
  -H 'Authorization: Bearer $TOKEN'

#Probe before creating

curl -X POST http://127.0.0.1:8088/api/agents/main/channels/probe \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "telegram",
    "config": {"token": "your-bot-token"}
  }'