# @chamvi/chat-whatsapp 中文文档 规范地址：https://npmcn.com/package/%40chamvi/chat-whatsapp/ 版本：0\.8\.0 npm 元数据更新时间：2026-11-08T20:18:05.957Z 中文译文更新时间：2026-11-09T23:09:53.611Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40chamvi/chat-whatsapp 原文对照：https://npmcn.com/package/%40chamvi/chat-whatsapp/?lang=original 项目主页：https://chamvi.dev/ 源码仓库：https://github.com/chamvi/chamvi ## 关键信息（来自 npm 元数据） - 包体积（解压后）：193 kB，12 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=26\.0\.0 - 运行依赖：1 个 - peer 依赖：chat ^4\.44\.0，baileys 7\.0\.0-rc14，@chamvi/app ^0\.8\.0，@chamvi/chat ^0\.8\.0，@chamvi/core ^0\.8\.0 - 首次发布：2026-11-02T11:19:53.764Z - 最新版本发布：2026-11-08T20:18:05.584Z - 近 30 天下载量：1699（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：10（近 12 个月 10 个） ## 中文简介 贝利斯的WhatsApp Web作为chamvi代理的聊天频道. ## 安装 ```sh npm install @chamvi/chat-whatsapp ``` 也可以使用：`pnpm add @chamvi/chat-whatsapp`、`yarn add @chamvi/chat-whatsapp`、`bun add @chamvi/chat-whatsapp` ## README ![@chamvi/chat-whatsapp](https://raw.githubusercontent.com/chamvi/chamvi/master/.github/assets/logo.svg) # @chamvi/chat-whatsapp (英语) **查姆维特工的WhatsApp Web.** 贝利斯的Chat SDK适配器, 插入到一个 `@chamvi/chat` 频道. [![npm version](https://img.shields.io/npm/v/@chamvi/chat-whatsapp)](https://www.npmjs.com/package/@chamvi/chat-whatsapp) [![CI](https://github.com/chamvi/chamvi/actions/workflows/ci.yml/badge.svg)](https://github.com/chamvi/chamvi/actions/workflows/ci.yml) [![License](https://img.shields.io/npm/l/@chamvi/chat-whatsapp)](https://github.com/chamvi/chamvi/blob/master/packages/chat-whatsapp/LICENSE) * * * **目录** - [安装](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-installation) - [使用量](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-usage) - [限制](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-limits) - [业务](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-operations) - [使用@ chamvi/ app](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-with-chamviapp) - [API 密码](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-api) - [许可证](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-license) ## 安装 ```bash npm install @chamvi/chat-whatsapp @chamvi/chat @chamvi/core @chamvi/http chat baileys@7.0.0-rc14 --save ``` 仅限无害环境管理,节点.js `>=26.0.0`。 。 。 . `@chamvi/chat`, (中文(简体) ), `@chamvi/core`, (中文(简体) ), [`chat`](https://www.npmjs.com/package/chat) (Chat SDK,4.44或后在 4.x行)和 `baileys` 是同伴的依赖关系; `baileys` 被钉入到一个版本的chamvi的适配器上`7.0.0-rc14`) (中文(简体) ). `smob` 是唯一的运行时间依赖。 软件包只使用 `@chamvi/chat`公共API:它的频道是 `chatChannel()` 和WhatsApp的钩子一样 `platform` (单位:千美元)[`IChatPlatform`](https://www.npmjs.com/package/@chamvi/chat#platform-packages)) (中文(简体) ). ## 使用量 `createWhatsAppChat()` 构建 Chat SDK `Chat`,“WhatsApp”及其“适配器” `chatChannel()`。在引擎上注册频道,订阅代理 `channel.on()` 并用工具回复 `ctx.channels.findOneOrFail('chat').emit()`数字 : ```typescript import type { LanguageModel } from 'ai'; import { z } from 'zod'; import { Engine, createMemoryStore, defineModelAgent, defineTool, } from '@chamvi/core'; import type { IEngine } from '@chamvi/core'; import { createWhatsAppChat } from '@chamvi/chat-whatsapp'; import type { WhatsAppChatOptions } from '@chamvi/chat-whatsapp'; export function createWhatsAppEngine( model: LanguageModel, // auth: your secure session store; state: a Chat SDK state adapter options: Pick, ): IEngine { const { WHATSAPP_SENDERS, APP_URL } = process.env; if (!WHATSAPP_SENDERS || !APP_URL) { throw new Error('Set WHATSAPP_SENDERS (phone number jids, comma separated) and APP_URL.'); } const whatsapp = createWhatsAppChat({ // a non-secret alias of the account, not its phone number account: 'assistant', // only these senders start runs; everybody else is ignored policy: { senders: WHATSAPP_SENDERS.split(',') }, resolveInvoker: (identity) => ({ id: identity.sender, kind: 'whatsapp', permissions: [], }), // a link to the approval in the chamvi UI: ids only, answered there approvalUrl: ({ runId, approvalId }) => `${APP_URL}/ui/approvals?run=${encodeURIComponent(runId)}&approval=${encodeURIComponent(approvalId)}`, ...options, }); const reply = defineTool({ description: 'Reply in the chat the message came from.', inputSchema: z.object({ text: z.string() }), execute: async ({ text }, { context }) => { // the source chat: no address needed await context.channels.findOneOrFail('chat').emit({ body: text }); return 'sent'; }, }); const assistant = defineModelAgent({ name: 'assistant', model, instructions: 'You are the owner\'s assistant on WhatsApp. Answer with the reply tool.', // one memory per direct chat and one per group conversation: true, // direct messages and mentions in an allowed group channels: [whatsapp.channel.on()], tools: { reply }, }); return new Engine({ // memory store: conversations included; use @chamvi/store-db in production store: createMemoryStore({ clock: options.clock }), agents: [assistant], channels: [whatsapp.channel], clock: options.clock, conversations: { authorize: ({ agent }) => agent === 'assistant' }, }); } ``` 当设置建成时, 没有任何连接: 频道的 `start` (引擎的)初始化Chat,获得认证租赁,再构建套接字. 虽然账户没有对齐, `onPairing` 接收用于为电话渲染的 QR 引用( 它旋转); 它从未达到日志或 `onError`。 。 。 . `setup.status()` (和 `onStatus`报告 `stopped`, (中文(简体) ), `connecting`, (中文(简体) ), `pairing`, (中文(简体) ), `connected`, (中文(简体) ), `disconnected`, (中文(简体) ), `logged-out`, (中文(简体) ), `held-elsewhere` (另一个进程举行会话;开始重试而不是失败)或 `failed` (会话存储失败) ; `setup.reset()` 清除会话并再次对对而不重新启动(在 `held-elsewhere`) (中文(简体) ). `auth` 是一个 `IWhatsAppAuthProvider`数字 : `createStoreWhatsAppAuth({ vault, connection })` 将会话封入 chamvi 商店( 连接库 `@chamvi/core`)或自给(参见 [业务](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-operations)) (中文(简体) ). 与 `@chamvi/app`, (中文(简体) ), [`whatsappModule()`](https://npmcn.com/package/%40chamvi/chat-whatsapp/#readme-with-chamviapp) 给店主打电话. `state` 是一个聊天SDK `StateAdapter`; chamvi的摄取量并不取决于其分化. 谁可能开始运行是 `policy`数字 : | 政策 | 允许 | | --- | --- | | `{ senders: [...] }` | 所列电话号码 jids 的直接信息(`@s.whatsapp.net`,没有设备后缀) | | `groups: [...]` | 列表组 jids 中的信件 (`@g.us`)来自被允许的发送者,默认只有在它们提到bot时(bot)`requireGroupMention: false` 放下那个 | | `{ open: true }` | 任何已解决的发送者; `resolveInvoker` 决定( 未定义否认) | 消息只有在其身份被验证、政策允许且 `resolveInvoker` 指定一个引用者。 机器人自己的消息,未知的发件人和一个其LID无法通过贝利斯认证的映射解决到一个电话号码的发件人被默默地拒绝:没有运行,没有回复,没有下载. 订阅、答复、核准、内存和信任 [`@chamvi/chat`](https://www.npmjs.com/package/@chamvi/chat):一个消息的对话是: `{ account, chat jid, direct: | group: }`,所以一个团体在其成员之间共享一个记忆. ## 限制 - 文本仅限,没有媒体下载,没有历史,没有信息分割(`CHAT_TEXT_MAX_CHARS`),与每个聊天频道一样. - 交付至少是一次:每次发送都携带从消息密钥中衍生出来的WhatsApp消息id,所以重试再使用;WhatsApp是否将这样的重复投放未验证. - 不失所取或下行摄取. 在连接器下架时到达的消息,或进程在被存储之前丢失的消息,不会被后取. ## 业务 通过贝利斯的WhatsApp Web是 **非正式协议**:WhatsApp可能更改或限制账户. 使用一个你能承受的账户 丢失并读取 [何等App 向导](https://chamvi.dev/deployment/whatsapp) 在现场直播之前 简而言之: - **会话存储.** `createStoreWhatsAppAuth()` (和 `whatsappModule()`(a) 存储证书和信号密钥AES-256-GCM `CHAMVI_ENCRYPTION_KEYS`,每批原子和栅栏 通过租赁 `connection:` (TTL 60 s, 每20 s更新一次): 杀后 - 9 下一个开始显示 `held-elsewhere` 并在租约到期后连接。 失去密钥意味着再次重设并配对(重设后在新数据密钥下再创建连接). 自己的供养者(`acquire(signal, { reset? })` - > (中文) `{ auth, saveCreds, flush, release, lost? }`)必须坚持以解剖和序列方式进行验证和信号密钥,只取位置(第二个持有人拒绝使用) `ConnectionHeldError`和, 打开 `reset`中,当会话占据位置时,会话会空出。 chamvi用租赁的一代守护每一次授权呼叫,在释放前冲出并释放每近的租赁:一个失败的冲出被报告,并写道过活 `WHATSAPP_SHUTDOWN_TIMEOUT_MS` 报告(30 s)一旦和解,即予以释放。 结束套接字有相同的长度,所以一个死链永远不能离开租约. - **一个连接器.** 每个账户进行一次部署, `Recreate`停下来,不要复制两本. - **配对** 仅由 QR (`onPairing`的连接页面 `whatsappModule()`;没有电话号码码. - **重新连接**: 意外的近距离连接与后退( )`WHATSAPP_RECONNECT`:2 s增长到30 s,12个尝试. 登录( 401) 或替换会话( 440) 不: 重置( )`setup.reset()`,或者在仪表板上重设会话)并再次对接. - **停下来** 结束套接字, 拒绝稍后的认证写入并冲出 。 Baileys可能重新测试一个密钥输入拒绝的站口的解密器(约30 s,无结果);chamvi不能保证这种消息在重启后得到处理. - **日志**: Baileys自己的日志机是无声的(它会携带配对材料),这也隐藏了它的解密和LID警告. ## 使用@ chamvi/ app ```ts import { createApp } from '@chamvi/app'; import { whatsappModule } from '@chamvi/chat-whatsapp/module'; const whatsapp = whatsappModule({ // the session's connection: sealed in the app store, shown at /ui/connections/whatsapp connection: 'whatsapp', account: 'assistant', state, policy: { senders: ['491701111111@s.whatsapp.net'] }, resolveInvoker: (identity) => ({ id: identity.sender, kind: 'whatsapp', permissions: [] }), }); export default createApp({ // agents subscribe with whatsapp.on() agents: [assistant], modules: [whatsapp], conversations: { authorize: ({ agent }) => agent === 'assistant' }, }); ``` `whatsappModule()` (单位:千美元)`@chamvi/app` 是一个可选对等点) takes `createWhatsAppChat()`选项 `auth`, (中文(简体) ), `onPairing` 财务报告和审定财务报表 `onStatus`附加时 `connection`, (中文(简体) ), `leaseTtlMs` 和可选 `approvalUrl` (默认:下面的仪表板) `CHAMVI_PUBLIC_URL`) (中文(简体) ). 在设置中它需要 `CHAMVI_ENCRYPTION_KEYS` (单位:千美元)`:`,逗号分隔,第一个活动;在未设置或变形时设置失败命名),将频道贡献给 `AppToken.CHANNELS` 连接控件到 `AppToken.CONNECTIONS`: 仪表板的连接页显示状态,并 `connection::write` 中,只包含 QR 和 重置 会话。 租的只有引擎启动时才有 所以 `chamvi start --check` 财务报告和审定财务报表 `chamvi run-job` 获取和写什么. 有了你自己的供养者, `chatModule({ channel: setup.channel })` 联 合 国 `@chamvi/chat/module` 捐款a `createWhatsAppChat()` 改为频道. ## API 密码 | 导出 | 持有 | | --- | --- | | `createWhatsAppChat(options)` | `{ chat, ingress, channel, status(), reset(), conversation() }` | | `createStoreWhatsAppAuth({ vault, connection, owner?, leaseTtlMs? })` | 存储支持 `IWhatsAppAuthProvider`· ; `WHATSAPP_CONNECTION_TYPE` `'whatsapp'` | | `whatsappModule(options)` (单位:千美元)`/module`(中文(简体) ) | `WhatsAppModule { channel, handle, on(), to(), conversation(), status(), reset() }`, (中文(简体) ), `WhatsAppModuleOptions` | | 类型 `WhatsAppChatOptions`, (中文(简体) ), `WhatsAppChatSetup`, (中文(简体) ), `StoreWhatsAppAuthOptions`, (中文(简体) ), `WhatsAppPolicy`, (中文(简体) ), `WhatsAppIdentity`, (中文(简体) ), `IWhatsAppAuthProvider`, (中文(简体) ), `WhatsAppAuthLease`, (中文(简体) ), `WhatsAppPairing`, (中文(简体) ), `WhatsAppConnectionStatus`, (中文(简体) ), `WhatsAppSocket`, (中文(简体) ), `WhatsAppSocketFactory` | | | `WHATSAPP_ADAPTER_NAME` `'whatsapp'`, (中文(简体) ), `WHATSAPP_RECONNECT`, (中文(简体) ), `WHATSAPP_SHUTDOWN_TIMEOUT_MS` 30 000人 | | | 错误代码 `whatsapp_auth`, (中文(简体) ), `whatsapp_connection`, (中文(简体) ), `whatsapp_logged_out` (单位:千美元)`WHATSAPP_*_ERROR_CODE`(中文(简体) ) | | 整个选项参考是 [何等App 向导](https://chamvi.dev/deployment/whatsapp)。 。 。 . ## 许可证 由 所制 原载 [Apache 许可证 2.0](https://npmcn.com/package/%40chamvi/chat-whatsapp/LICENSE)。 。 。 . ## 常见问题 ### @chamvi/chat-whatsapp 是什么？ 贝利斯的WhatsApp Web作为chamvi代理的聊天频道\. ### 如何安装 @chamvi/chat-whatsapp？ 在项目目录运行 npm install @chamvi/chat-whatsapp，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：chat（^4\.44\.0）、baileys（7\.0\.0-rc14）、@chamvi/chat（^0\.8\.0）、@chamvi/core（^0\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @chamvi/chat-whatsapp 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @chamvi/chat-whatsapp 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @chamvi/chat-whatsapp 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @chamvi/chat-whatsapp 可以商用吗？ @chamvi/chat-whatsapp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @chamvi/chat-whatsapp 的下载量有多少？ 根据 npm 官方下载统计，@chamvi/chat-whatsapp 在 2026/10/10 – 2026/11/08 这 30 天内被下载 1,699 次，日均约 57 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @chamvi/chat-whatsapp 还在维护吗？ 最新版本 0\.8\.0 发布于 2026/11/09（1 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。