Channels API: Connect Agents to IM Platforms in Octop

Create, update, test, and delete IM channel connections for Octop agents. Endpoints for Feishu, WeCom, DingTalk, Telegram, and more.

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

Method	Path	Auth	Description
GET	/agents/{aid}/channels	owner	List channels for an agent
POST	/agents/{aid}/channels	owner	Create a new channel
GET	/agents/{aid}/channels/{cid}	owner	Get channel details
PATCH	/agents/{aid}/channels/{cid}	owner	Update channel config or name
DELETE	/agents/{aid}/channels/{cid}	owner	Delete channel
POST	/agents/{aid}/channels/{cid}/test	owner	Test channel connection
POST	/agents/{aid}/channels/qq/qrcode/generate	owner	Start QQ Bot QR binding; returns qrcode_url / qrcode_token
POST	/agents/{aid}/channels/qq/qrcode/poll	owner	Poll QQ QR result; body {qrcode_token} → credentials on success

​

Create a channel

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

Feishu

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": "..."
    }
  }'

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:

Field	Values	Default	Meaning
response_mode	invoke, stream	invoke	invoke is Final only: the chat app receives one finished reply. stream is Live progress. QQ C2C ignores this key.
c2c_streaming	bool	true on save	QQ private chat only. true uses official stream_messages. false sends one static markdown reply. Old keys streaming / response_mode do nothing for C2C.
show_thinking	bool	false	Show thinking. Unavailable when the mode is Final only.
show_tool_hints	bool	false	Show tool hints. Unavailable when the mode is Final only. On QQ C2C, extra tool bubbles consume passive-reply quota.

​

Supported kinds

kind	Platform
weixin	WeChat
qq	QQ
wecom	WeCom
feishu	Feishu
yuanbao	Tencent Yuanbao
dingtalk	DingTalk
telegram	Telegram
xiaoyi	Huawei Xiaoyi
mqtt	MQTT

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).

Octop validates the kind value against its registered channel builders. If you pass an unrecognised platform name, the server returns 400 CHANNEL_KIND_UNSUPPORTED.

​

QQ QR bind

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

Generate

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

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

​

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

curl -X POST http://127.0.0.1:8088/api/agents/main/channels/ch_abc/test \
  -H 'Authorization: Bearer $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

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

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

​

Probe before creating

Use the probe endpoint to validate a candidate config before committing to a full channel creation. Send POST /agents/{aid}/channels/probe with the same kind and config you plan to use — it returns {"ok": true} or {"ok": false, "reason": "...", "detail": "..."} without persisting anything.

cURL

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"}
  }'