> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash Feishu theme={null}
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 theme={null}
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:

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

> [!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 theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/main/channels/qq/qrcode/generate \
  -H 'Authorization: Bearer $TOKEN'
```

```bash Poll theme={null}
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.

## 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 theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/main/channels/ch_abc/test \
  -H 'Authorization: Bearer $TOKEN'
```

```json Response (success) theme={null}
{"ok": true}
```

```json Response (failure) theme={null}
{"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 theme={null}
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 theme={null}
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 theme={null}
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"}
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.