# @clisbot/channels-zalo 中文文档

规范地址：https://npmcn.com/package/%40clisbot/channels-zalo/

版本：2\.2\.3
npm 元数据更新时间：2026-11-05T01:29:15.394Z
中文译文更新时间：2026-11-10T02:10:05.579Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40clisbot/channels-zalo
原文对照：https://npmcn.com/package/%40clisbot/channels-zalo/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：270 kB，99 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-10-10T10:32:29.711Z
- 最新版本发布：2026-11-05T01:29:15.205Z
- 近 30 天下载量：3747（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

In-repo Zalo官方账户(Bot API)频道垂直(目标分类账切片16). 从扩展名/zalo/src@5d8067a4483上接: Bot API客户端,令牌/账户解析度,探测器,发送路径,消息工具动作和webhook请求处理器

## 安装

```sh
npm install @clisbot/channels-zalo
```

也可以使用：`pnpm add @clisbot/channels-zalo`、`yarn add @clisbot/channels-zalo`、`bun add @clisbot/channels-zalo`

## README

# @clisbot/频道-zalo

在repo Zalo官方账户(Bot API)频道垂直(目标分类账切片) 16) 从 `extensions/zalo/src@5d8067a4483` 看到了吗 `upstream-sync.json` 页:1 逐文件映射、偏差(`D-ZL-0xx`)和省略的内容.

Zalo船没有SDK:上游手卷其Bot API客户端 `fetch` 财务报告和审定财务报表 只取决于 `zod` (单位:千美元)`4.4.3`,上游版本),这就是这个软件包 也一样. `undici` 仅用于代理代理代理,在动态导入中 discord 垂直使用相同的形状.

这是 **官方账户机器人** 频道 (`bot-api.zaloplatforms.com`) (中文(简体) ). 扎罗 个人(`zalouser`,QR-login个人账户)是一个不同的上游账户 扩展和不同的切片(17).

枢纽接线器在后续片中落地. [HUB-WIRING.MD (英语)](https://npmcn.com/package/%40clisbot/channels-zalo/HUB-WIRING.md) 这是 交接文件是用Hub方面拥有的东西制作的,并保留着记录; `../../../docs/features/channels/README.md` 描述平台为已建.

## 现场测试需要什么

自己提供这些,放回原地 `.env`。这个软件包永远不会 读取 `.env` 而这里没有价值是真正的证明——只有名字。 这个 `ZALO_PERSONAL_TEST_*` 已经输入的 ids `.env` 属于切片17,不是这个 频道.

### Zalo 设置

1.  创建(或使用)a **扎洛官方账户** 时间 [哦,扎罗,我](https://oa.zalo.me/)。 。 。 .
2.  单位 **Zalo 瓶创建者** (单位:千美元)`bot.zaloplatforms.com`为OA和 复制它的标志。 这个标志是整个证书——没有应用代码,没有 OAuth和没有签名密钥.
3.  跟着Zalo个人账户里的机器人 把它加进去 测试组,如果您想要分组案例.
4.  投票模式不需要别的 Webhook 模式还需要一个公众 HTTPS 端点和您选择的秘密( 8–256 个字符) .

### 试验表面

| 新闻 var | 一定是这样 |
| --- | --- |
| `ZALO_BOT_TOKEN` | 测试对象是Zalo Bot创造者 永远不要承诺. |
| `ZALO_TEST_CHAT_ID` | 机器人和人类测试者之间的DM聊天id(a) `message.*.received` 事件显示它. |
| `ZALO_TEST_GROUP_ID` | 增加了一个组,用于该组+提及案例. |
| `ZALO_TEST_BOT_ID` | 机器人的自有身份证明`getMe` → `result.id`),用于自带信息过滤. |
| `ZALO_TEST_BOT_NAME` | 那个机器人 `account_name`,这是一个群体提到的匹配. |
| `ZALO_TEST_IMAGE_URL` | 用于输出的公开 HTTPS 图像 URL `sendPhoto` 案例. |
| `ZALO_WEBHOOK_URL` | 仅Webhook模式:公开的HTTPS URL Zalo发布到. |
| `ZALO_WEBHOOK_SECRET` | 只使用 Webhook 模式: 8–256- Char 符号在 `x-bot-api-secret-token`。 。 。 . |
| `ZALO_API_URL` | 可选的 覆盖 API 基础(`https://bot-api.zaloplatforms.com`)用于假服务器. |

驱动程序/ bot- under - test 拆分是规则 (CLAUDE.md,"需要的Slack和Telegram E2E角色"):一个直接的 `sendText` 是一个 仅限外出抽烟测试. 所需要的证据是 **外部发送方 运输方 代理翻转 ~ 在同一聊天中回复**,然后读取匹配消息 id的回转 发送返回。 在Zalo上,外部发送者是一个 **人类扎洛账户** 给机器人发信息:机器人API 无法让一个机器人驱动另一个机器人,它 也没有回读终点( 无) `getMessages`,没有历史,所以读回 证据的一方是人类自己的客户 加上 `message_id` 发送 已经返回.

**现场投票E2E今天可以投票** 与 `ZALO_BOT_TOKEN` 一个人 韦伯克 E2E 在公共端点被屏蔽;见 [HUB-WIRING.md 第6节](https://npmcn.com/package/%40clisbot/channels-zalo/HUB-WIRING.md#6-the-public-endpoint-webhook-mode-only)。 。 。 .

### 最小账户配置

```yaml
channel: zalo
accountId: main
connectionId: <hub connection id>
# webhookUrl absent → long polling, which is the mode a dev host can run.
mediaMaxMb: 5
botNames: ["<ZALO_TEST_BOT_NAME>"] # group mention aliases
routes:
  - match: { kind: dm }
    agent: <agent>
    environment: <environment>
  - match: { kind: channel, ids: ["<ZALO_TEST_GROUP_ID>"] }
    agent: <agent>
    environment: <environment>
```

机器人的标志 住在Hub连接的证书下 `botToken`中,没有 这个文件.

## 今天获得支持

**入境** 投票时间长(`getUpdates`)或HTTP webhook,两者都承认 在运输前:

-   `message.text.received` − a 个 `message` 转身,或 `command` 当身体转动时 是一个领先 `/verb`。 。 。 .
-   `message.image.received` − a 个 `message` 转过身来 照片下载到账户的媒体目录并折叠为 `[Attached files]`。失败或过大下载保留上游 `[zalo image attachment unavailable]` 通知,所以代理仍然学习 图像已发送 .
-   直接聊天和组. 一个DM总是 `wasMentioned`; 组消息是 提到它命名机器人时(D-ZL-012).
-   机器人自己的信件和由机器人撰写的信件被过滤,除非 `allowBots`。 。 。 .

Webhook 请求以恒定时间认证 `x-bot-api-secret-token` 比较 **在此之前** 身体被读取 在上游的后面 速率限制 / 方法 / 内容类型 守护器, 200 则只写于 事件被持久地承认——一个失败的承认答案500,所以Zalo repelivers, a 错误的信封回答400 所以它不会.

投票没有抵消,也没有退缩(瓶子API最多返回一次) 更新并且永远不再保留它,所以循环在它发布之前就持久地承认了 下次拨打时,请重试一个失败的录入位置,然后以一个 只有在预算用完后(D-ZL-015)才会出错级行.

**出境**:带有上游2000-Char块和UTF-16-安全截取的文本; hTTPS URL 的图像 `sendPhoto` (以文本为标题),后面 sSRF的主保镖.

**信件工具动作**数字 : `send` ——整个扎洛消息API.

## 不予支持

命名于此, 上面没有比它更多的内容 。 其中大部分是 平台限制,而不是端口缺口.

-   **文件上传** ——Bot API没有上传端点. `sendMedia` 员额a 明显通知和报告 `mediaPosted: false` (D-ZL-016) (中文(简体) ). 上游的风景 工作周期(`outbound-media.ts`,将文件托管在账户本身的 webhook上 来源)需要HTTPS的公用端点,而省略.
-   **编辑、删除、反应、针头、民调、按钮、原生命令、线程** —— 说 没有终点. `supportsAction` 拒绝他们 所以Hub回答 `unsupported_action` 而不是运输错误.
-   **回读/ 历史** 没有终点。 送货由退回者确认 `message_id` 只有这个.
-   **标签和不支持的信件类型** 上游记录这些记录和 开始不转; 此端口保持了这一行为, 而不是创建一个机构 .
-   **打字指标** —— 说 `sendChatAction` 是在客户端并输出,但 没有什么能推动它:上游驱动它 从省略的答复管道 Hub的进步表面还没有Zalo运输.
-   **对等、许可列表、 dm/组政策执行** ——枢纽拥有接入权 (目标分类账23)。 账户的 `dmPolicy` 编号 : `allowFrom` 编号 : `groupPolicy` (b) 上游 `group-access.ts` 解析器被移植到枢纽处使用.
-   **设置/ 医生表面, 批准权限, 会话路径** ——"开放法" 巫师, `doctor` 树木、核准-自动能力和出站会话路线 建设者省略;枢纽自有上岗,审批和出行.

## 版式

```
src/
  api.ts timeouts.ts               ← upstream Bot API client + its deadlines
  token.ts accounts.ts types.ts    ← upstream token/account resolution
  probe.ts proxy.ts group-access.ts ← upstream probe, proxy cache, group policy
  send.ts actions.ts actions.runtime.ts ← upstream send path + message-tool adapter
  webhook-spool.ts monitor.webhook.ts   ← upstream envelope schemas + request handler
  runtime-api.ts runtime.ts             ← upstream host binding + runtime slot
  channel-actions.ts outbound.ts        ← Fusion: Hub drive surface
  lifecycle/start-account.ts            ← Fusion: L4 account lifecycle
  fusion/                               ← Fusion: every boundary, one per D-ZL-0xx
    account-config.ts   Hub account carrier → upstream account resolution
    admission.ts        durable admission before the ack / the next poll
    inbound-adapter.ts  update → ChannelInboundEvent (kind + facts)
    polling-session.ts  the getUpdates loop
    webhook-session.ts  the owned node:http listener
    ssrf.ts             the media-URL host guard
    proxy-fetch.ts      the proxy-agent fetch
    secret-file.ts      the credential-file reader
```

## 常见问题

### @clisbot/channels-zalo 是什么？

In-repo Zalo官方账户\(Bot API\)频道垂直\(目标分类账切片16\)\. 从扩展名/zalo/src@5d8067a4483上接: Bot API客户端,令牌/账户解析度,探测器,发送路径,消息工具动作和webhook请求处理器

### 如何安装 @clisbot/channels-zalo？

在项目目录运行 npm install @clisbot/channels-zalo，或使用 pnpm add / yarn add / bun add。

### @clisbot/channels-zalo 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @clisbot/channels-zalo 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @clisbot/channels-zalo 可以商用吗？

@clisbot/channels-zalo 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @clisbot/channels-zalo 的下载量有多少？

根据 npm 官方下载统计，@clisbot/channels-zalo 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,747 次，日均约 125 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @clisbot/channels-zalo 还在维护吗？

最新版本 2\.2\.3 发布于 2026/11/05（5 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/10/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。