---
title: "消息通道 API：即时通讯与通知"
description: "Halo HTTP API 消息通道接口：连接和断开即时通讯通道、把聊天绑定到数字人、读取聊天记录、测试通知。"
type: "reference"
audience: ["developer"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/developers/api/channels.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# API：消息通道

Halo HTTP API 消息通道接口：连接和断开即时通讯通道、把聊天绑定到数字人、读取聊天记录、测试通知。

消息通道把数字人接入企业微信、飞书、微信等即时通讯平台，通知则用于向外发送提醒。用这些接口连接和断开通道、把聊天绑定到数字人、读取已绑定聊天的记录，并测试通知。新建通道和填写凭据请在 **设置 › 消息通道** 中完成。

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 `$HALO_URL` 和 `$HALO_TOKEN` 按[快速上手](https://hello-halo.cc/docs/developers/quickstart.html)设置；地址、鉴权和错误约定见 [HTTP API 概览](https://hello-halo.cc/docs/developers/api/)。

| 操作 | 端点 |
| --- | --- |
| [清空数字人在已绑定即时通讯聊天中的记录](https://hello-halo.cc/docs/developers/api/digital-human.html#post-api-apps-appid-im-chat-clear) (数字人) （不可撤销） | `POST /api/apps/:appId/im-chat/clear` |
| [读取数字人在已绑定即时通讯聊天中的记录](https://hello-halo.cc/docs/developers/api/digital-human.html#get-api-apps-appid-im-chat-messages) (数字人) | `GET /api/apps/:appId/im-chat/messages` |
| [停止数字人在已绑定即时通讯聊天中正在生成的回复（保留记录）](https://hello-halo.cc/docs/developers/api/digital-human.html#post-api-apps-appid-im-chat-stop) (数字人) | `POST /api/apps/:appId/im-chat/stop` |
| [检查飞书机器人是否真正可达，而不只是已连接](#post-api-feishu-bot-reachability) | `POST /api/feishu-bot/reachability` |
| [获取本版本为新通道设定的默认访客权限](#get-api-im-channels-permission-defaults) | `GET /api/im-channels/permission-defaults` |
| [列出可用的即时通讯通道类型及其配置字段](#get-api-im-channels-providers) | `GET /api/im-channels/providers` |
| [重新连接一个即时通讯通道](#post-api-im-channels-reconnect) | `POST /api/im-channels/reconnect` |
| [按已保存的配置重新加载所有即时通讯通道](#post-api-im-channels-reload) | `POST /api/im-channels/reload` |
| [获取所有即时通讯通道的连接状态，或用 ?instanceId= 查询一个](#get-api-im-channels-status) | `GET /api/im-channels/status` |
| [列出数字人的全部聊天线程，包括它自己的和即时通讯中的](#get-api-im-sessions) | `GET /api/im-sessions` |
| [列出数字人借另一位数字人的机器人推送到的聊天](#get-api-im-sessions-linked) | `GET /api/im-sessions/linked` |
| [从会话登记中移除一个聊天绑定](#post-api-im-sessions-remove) | `POST /api/im-sessions/remove` |
| [为聊天绑定设置自定义显示名称](#post-api-im-sessions-set-custom-name) | `POST /api/im-sessions/set-custom-name` |
| [设置运行结束后是否自动把结果推送到这个聊天](#post-api-im-sessions-set-proactive) | `POST /api/im-sessions/set-proactive` |
| [允许或停止数字人借另一位数字人的机器人推送到某个聊天](#post-api-im-sessions-set-push-link) | `POST /api/im-sessions/set-push-link` |
| [清除缓存的通知渠道访问令牌](#post-api-notify-channels-clear-cache) | `POST /api/notify-channels/clear-cache` |
| [读取产品级的通知渠道定制](#get-api-notify-channels-product-config) | `GET /api/notify-channels/product-config` |
| [通过一个已配置的通知渠道发送测试通知](#post-api-notify-channels-test) | `POST /api/notify-channels/test` |
| [重新连接所有已配置的企业微信机器人](#post-api-wecom-bot-reconnect) | `POST /api/wecom-bot/reconnect` |
| [查询企业微信机器人通道是否已配置并连接](#get-api-wecom-bot-status) | `GET /api/wecom-bot/status` |
| [清除微信机器人的凭据并停止它](#post-api-weixin-ilink-disconnect) | `POST /api/weixin-ilink/disconnect` |
| [为已配置的微信机器人设置令牌](#post-api-weixin-ilink-save-token) | `POST /api/weixin-ilink/save-token` |

## 检查飞书机器人是否真正可达，而不只是已连接 {#post-api-feishu-bot-reachability}

`POST /api/feishu-bot/reachability` （助手可调用）

- A Feishu app awaiting administrator release connects normally and receives nothing, so "connected" alone does not mean the bot works. inboundCount 0 with a long connectedSinceMs is the signature of that case. No credentials in this response.

**请求体**

```json
{
  "instanceId": "<instanceId — from GET /api/im-channels/status>"
}
```

**响应**

```ts
{success:true,data:{state,connectedSinceMs,lastInboundAgoMs,inboundCount,lastError?}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/feishu-bot/reachability" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"<instanceId — from GET /api/im-channels/status>"}'
```

## 获取本版本为新通道设定的默认访客权限 {#get-api-im-channels-permission-defaults}

`GET /api/im-channels/permission-defaults` （助手可调用）

**响应**

```ts
{success:true,data:{defaultEnabled?,defaultGuestAccess?,defaultGuestPolicy?:{allowedTools?},ownerIdHint?,ownerSetupGuideUrl?} | null}
```

**示例**

```bash
curl -s "$HALO_URL/api/im-channels/permission-defaults" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出可用的即时通讯通道类型及其配置字段 {#get-api-im-channels-providers}

`GET /api/im-channels/providers` （助手可调用）

- Schema only. No endpoint here creates an instance from it — the user creates instances in Settings &gt; Message Channels. Schema only (field definitions and empty defaults) — no configured instance data or secrets.

**响应**

```ts
{success:true,data:[{type,displayName,description,direction,configFields:[{key,label,type,placeholder?,required?}],defaultConfig}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/im-channels/providers" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 重新连接一个即时通讯通道 {#post-api-im-channels-reconnect}

`POST /api/im-channels/reconnect` （可撤销） （助手可调用）

**请求体**

```json
{
  "instanceId": "<instanceId — from GET /api/im-channels/status>"
}
```

**响应**

```ts
{success:boolean,error?}
```

**错误**

- 400 if instanceId is missing. success:false with an error message if the instanceId is unknown.

**示例**

```bash
curl -sX POST "$HALO_URL/api/im-channels/reconnect" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"<instanceId — from GET /api/im-channels/status>"}'
```

## 按已保存的配置重新加载所有即时通讯通道 {#post-api-im-channels-reload}

`POST /api/im-channels/reload` （可撤销） （助手可调用）

- Use after a config change made through another route to apply it without restarting Halo. Stops and rebuilds any instance whose config changed — brief interruption, no data lost.

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/im-channels/reload" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 获取所有即时通讯通道的连接状态，或用 ?instanceId= 查询一个 {#get-api-im-channels-status}

`GET /api/im-channels/status` （助手可调用）

- No credentials in this response. instanceId not found → {success:false,error}.

**查询参数**：`instanceId`

**响应**

```ts
{success:true,data:{id,type,enabled,connected,state?,appId,appName?,reason?,identityResolution?}[] | <single instance object>}
```

**示例**

```bash
curl -s "$HALO_URL/api/im-channels/status" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出数字人的全部聊天线程，包括它自己的和即时通讯中的 {#get-api-im-sessions}

`GET /api/im-sessions` （助手可调用）

- Optional ?appId= narrows it to one digital human. This is the only listing of its threads — there is no sessions/list beside sessions/create.
- source says what a thread is: "local" = a named thread the user created in Halo, "im" = a real chat with a person on an IM platform, "http" = created through this API.
- Reading or writing one thread needs a conversationId, which is not a field here — build it from four fields of the record: app-chat:&lt;appId&gt;:&lt;channel&gt;:&lt;chatType&gt;:&lt;chatId&gt;.
- Only "local" and "http" threads accept a message from this API. An "im" thread is refused on send — this API must not put words into a real conversation with a person.

**查询参数**：`appId`

**响应**

```ts
{success:true,data:[{appId,channel,source:"local"|"im"|"http",chatType:"direct"|"group",chatId,displayName,customName?,proactive,instanceId,pushLinks?:[{appId,autoSync}]}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/im-sessions" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 列出数字人借另一位数字人的机器人推送到的聊天 {#get-api-im-sessions-linked}

`GET /api/im-sessions/linked` （助手可调用）

- Each record is the session as the bot's own digital human holds it (its appId is that one). The asking digital human's entry in pushLinks says whether its run results are auto-pushed there.

**查询参数**：`appId`（必填）

**响应**

```ts
{success:true,data:[{appId,channel,chatType,chatId,displayName,instanceId,pushLinks:[{appId,autoSync}]}]}
```

**示例**

```bash
curl -s "$HALO_URL/api/im-sessions/linked?appId=<appId — a uuid from GET /api/apps>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 从会话登记中移除一个聊天绑定 {#post-api-im-sessions-remove}

`POST /api/im-sessions/remove` （可撤销） （助手可调用）

- removed:false means no matching session was found — not an error. Only removes display metadata (custom name, proactive flag, other digital humans' push links to it); the chat re-registers itself on its next inbound message, message history is not stored here.

**请求体**

```json
{
  "appId": "<appId — a uuid from GET /api/apps>",
  "channel": "wecom-bot",
  "chatId": "<chatId — from GET /api/im-sessions>"
}
```

**响应**

```ts
{success:true,data:{removed:boolean}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/im-sessions/remove" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId — a uuid from GET /api/apps>","channel":"wecom-bot","chatId":"<chatId — from GET /api/im-sessions>"}'
```

## 为聊天绑定设置自定义显示名称 {#post-api-im-sessions-set-custom-name}

`POST /api/im-sessions/set-custom-name` （可撤销） （助手可调用）

**请求体**

```json
{
  "appId": "<appId — a uuid from GET /api/apps>",
  "channel": "wecom-bot",
  "chatId": "<chatId — from GET /api/im-sessions>",
  "name": "Sales Team Chat"
}
```

**响应**

```ts
{success:true} or {success:false,error}
```

**错误**

- 404 if no matching session exists yet.

**示例**

```bash
curl -sX POST "$HALO_URL/api/im-sessions/set-custom-name" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId — a uuid from GET /api/apps>","channel":"wecom-bot","chatId":"<chatId — from GET /api/im-sessions>","name":"Sales Team Chat"}'
```

## 设置运行结束后是否自动把结果推送到这个聊天 {#post-api-im-sessions-set-proactive}

`POST /api/im-sessions/set-proactive` （可撤销） （助手可调用）

**请求体**

```json
{
  "appId": "<appId — a uuid from GET /api/apps>",
  "channel": "wecom-bot",
  "chatId": "<chatId — from GET /api/im-sessions>",
  "proactive": true
}
```

**响应**

```ts
{success:true} or {success:false,error}
```

**错误**

- 404 if no matching session exists yet — the chat must have messaged the digital human at least once.

**示例**

```bash
curl -sX POST "$HALO_URL/api/im-sessions/set-proactive" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId — a uuid from GET /api/apps>","channel":"wecom-bot","chatId":"<chatId — from GET /api/im-sessions>","proactive":true}'
```

## 允许或停止数字人借另一位数字人的机器人推送到某个聊天 {#post-api-im-sessions-set-push-link}

`POST /api/im-sessions/set-push-link` （可撤销） （助手可调用）

- link:{autoSync} adds the chat to the digital human's push targets or updates it; autoSync:true also pushes its run results there. link:null removes it.
- Replies in that chat still go to the digital human the bot answers for. 404 when the session does not exist, is not an IM chat, or is the digital human's own.

**请求体**

```json
{
  "appId": "<appId of the digital human that pushes>",
  "session": {
    "appId": "<the session's own appId>",
    "channel": "wecom-bot",
    "chatId": "<chatId — from GET /api/im-sessions>"
  },
  "link": {
    "autoSync": false
  }
}
```

**响应**

```ts
{success:true} or {success:false,error}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/im-sessions/set-push-link" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId of the digital human that pushes>","session":{"appId":"<the session'\''s own appId>","channel":"wecom-bot","chatId":"<chatId — from GET /api/im-sessions>"},"link":{"autoSync":false}}'
```

## 清除缓存的通知渠道访问令牌 {#post-api-notify-channels-clear-cache}

`POST /api/notify-channels/clear-cache` （可撤销） （助手可调用）

- Worth trying when a channel that used to work starts failing to authenticate — the next send fetches a fresh token. It changes no configuration.

**响应**

```ts
{"success":true}  // no data
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/notify-channels/clear-cache" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 读取产品级的通知渠道定制 {#get-api-notify-channels-product-config}

`GET /api/notify-channels/product-config` （助手可调用）

- Presentation only — help links this build shows per channel. data is null when the build customises nothing. It does not say which channels the user configured.

**响应**

```ts
{"success":true,"data":{"wecom":{"docs":{...}},"email":{"docs":{...}}}}
```

**示例**

```bash
curl -s "$HALO_URL/api/notify-channels/product-config" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 通过一个已配置的通知渠道发送测试通知 {#post-api-notify-channels-test}

`POST /api/notify-channels/test` （可撤销） （助手可调用）

- `channelType` is one of `wecom`, `dingtalk`, `feishu`, `email` or `webhook`.
- Delivers a real message: a fixed test text through that channel. The text cannot be changed, so this is a test, not a way to send notifications.
- "No notification channels configured" means none is set up yet; channels are set up in **Settings › Message Channels**.

**请求体**

```json
{
  "channelType": "wecom"
}
```

**响应**

```ts
{"success":true,"data":{...delivery result}}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/notify-channels/test" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channelType":"wecom"}'
```

## 重新连接所有已配置的企业微信机器人 {#post-api-wecom-bot-reconnect}

`POST /api/wecom-bot/reconnect` （可撤销） （助手可调用）

- A brief connection interruption while it reconnects — no data lost.

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/wecom-bot/reconnect" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 查询企业微信机器人通道是否已配置并连接 {#get-api-wecom-bot-status}

`GET /api/wecom-bot/status` （助手可调用）

- Legacy single-bot view (booleans only, no token). For per-instance detail use [`GET /api/im-channels/status`](#get-api-im-channels-status).

**响应**

```ts
{success:true,data:{configured:boolean,enabled:boolean,connected:boolean}}
```

**示例**

```bash
curl -s "$HALO_URL/api/wecom-bot/status" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 清除微信机器人的凭据并停止它 {#post-api-weixin-ilink-disconnect}

`POST /api/weixin-ilink/disconnect` （可撤销） （助手可调用）

- Clears the WeChat Bot credentials of this channel and stops it. Reconnecting needs the same token again ([`POST /api/weixin-ilink/save-token`](#post-api-weixin-ilink-save-token)) or a new QR pairing in **Settings › Message Channels**.

**请求体**

```json
{
  "instanceId": "<instanceId — from GET /api/im-channels/status>"
}
```

**响应**

```ts
{success:true} or {success:false,error}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/weixin-ilink/disconnect" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"<instanceId — from GET /api/im-channels/status>"}'
```

## 为已配置的微信机器人设置令牌 {#post-api-weixin-ilink-save-token}

`POST /api/weixin-ilink/save-token` （可撤销） （助手可调用）

- Optional fields: baseUrl, accountId.
- instanceId must already exist (created earlier in the Settings UI) — this route cannot create a new instance, only fill in its token.
- Never echoes the token back in the response.
- {success:false,error:"..."} when instanceId is not found in config.
- Takes over that channel identity immediately — a wrong token silently hijacks it until corrected.

**请求体**

```json
{
  "instanceId": "<instanceId — from GET /api/im-channels/status>",
  "botToken": "..."
}
```

**响应**

```ts
{success:true} or {success:false,error}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/weixin-ilink/save-token" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"<instanceId — from GET /api/im-channels/status>","botToken":"..."}'
```