> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# 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

| 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       |
| `POST`   | `/agents/{aid}/channels/dingtalk/qrcode/generate` | owner | Start DingTalk QR application authorization                             |
| `POST`   | `/agents/{aid}/channels/dingtalk/qrcode/poll`     | owner | Poll DingTalk authorization; creates and enables the channel on success |

## Create a channel

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


```bash 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": "..."
    }
  }'
```
```bash Telegram
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",
      "allowed_user_ids": ["123456789"]
    }
  }'
```


Optional `allowed_user_ids` limits who may message a Telegram bot. Omit or leave empty to allow any user the bot can see.

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` | web UI: `stream`; API fallback: `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        |
| `discord`  | Discord         |
| `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`).


> **WARNING**
> 
> 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:


```bash Generate
curl -X POST http://127.0.0.1:8088/api/agents/main/channels/qq/qrcode/generate \
  -H 'Authorization: Bearer $TOKEN'
```
```bash Poll
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`.


```bash Generate
curl -X POST http://127.0.0.1:8088/api/agents/main/channels/dingtalk/qrcode/generate \
  -H 'Authorization: Bearer $TOKEN'
```
```json Response
{
  "registration_id": "...",
  "qrcode_url": "https://...",
  "user_code": "ABCD-EFGH",
  "expires_in": 600,
  "interval": 5
}
```
```bash Poll
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.


```bash cURL
curl -X POST http://127.0.0.1:8088/api/agents/main/channels/ch_abc/test \
  -H 'Authorization: Bearer $TOKEN'
```
```json Response (success)
{"ok": true}
```
```json Response (failure)
{"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.


```bash 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`.


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


## Probe before creating


> **TIP**
> 
> 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.
> 



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

