# @copilotkit/channels-whatsapp 中文文档

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

版本：0\.12\.0
npm 元数据更新时间：2026-10-28T13:38:34.744Z
中文译文更新时间：2026-11-10T18:33:58.442Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40copilotkit/channels-whatsapp
原文对照：https://npmcn.com/package/%40copilotkit/channels-whatsapp/?lang=original
项目主页：https://github.com/CopilotKit/CopilotKit
源码仓库：https://github.com/CopilotKit/CopilotKit

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

- 包体积（解压后）：153 kB，93 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-07-08T19:58:53.381Z
- 最新版本发布：2026-10-28T13:38:34.268Z
- 近 30 天下载量：48803（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 45 个）

## 中文简介

CopilotKit JSX频道的WhatsApp Cloud API平台适配器 (@copilotkit/channels).

## 安装

```sh
npm install @copilotkit/channels-whatsapp
```

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

## README

# @ copilotkit/ channels- whatsapp (英语)

这个 **怎样 `PlatformAdapter`** 页:1 [`@copilotkit/channels`](https://npmcn.com/package/%40copilotkit/channels)它连接一个 任何AG-UI代理的WhatsApp业务号:通过Meta Cloud API webhook入侵, 以文本或交互式信息形式从 `@copilotkit/channels-ui` 联合来文十 词汇,不透明-id相互作用,和HITL.

你曾经将你的UI写成JSX(`@copilotkit/channels-ui`和驱动机器人与 `@copilotkit/channels`;这个包是唯一一个与WhatsApp Cloud API对话的.

适配器保存自己的WhatsApp Cloud API证书(`accessToken` 编号 : `phoneNumberId` /.)——在所管理的路径中,频道运行在副驾驶Kit内 情报配置 `CopilotRuntime` (有免费计划),开始和 拥有频道的生命周期. 新建并运行您的频道运行 sDK原始人也是一条支持路径.

## 安装

```sh
pnpm add @copilotkit/channels @copilotkit/channels-whatsapp
```

## 快速启动

```ts
import { createChannel } from "@copilotkit/channels";
import {
  whatsapp,
  defaultWhatsAppContext,
} from "@copilotkit/channels-whatsapp";
import { CopilotRuntime, CopilotKitIntelligence } from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";

const bot = createChannel({
  identifyUser: "platform",
  name: "support-bot", // project-unique Intelligence Channel name
  adapters: [
    whatsapp({
      accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
      phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
      appSecret: process.env.WHATSAPP_APP_SECRET!,
      verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
      port: 3000,
    }),
  ],
  agent: makeAgent(process.env.AGENT_URL!),
  tools: [...appTools],
  context: [...defaultWhatsAppContext, ...appContext],
});

// Every inbound text is for the bot — there is no @-mention concept on WhatsApp.
bot.onMessage(async ({ thread }) => {
  await thread.runAgent();
});

// The runtime owns the channel's lifecycle — there is no `bot.start()`.
const runtime = new CopilotRuntime({
  intelligence: new CopilotKitIntelligence({
    // apiUrl and wsUrl default to cloud-hosted CopilotKit Intelligence — override
    // both together only for a self-hosted deployment.
    apiKey: process.env.CPK_INTELLIGENCE_API_KEY!, // free tier available
  }),
  channels: [bot],
});

// Creating the listener starts the Channel's connection.
const listener = createCopilotNodeListener({ runtime });
// Optional: await that activation so a broken config fails startup loudly.
await listener.channels.ready(); // listener.channels.stop() tears it down
console.log("[whatsapp-bot] listening for webhooks");
```

`whatsapp(opts)` 返回 a `WhatsAppAdapter`打开 HTTP 服务器 `port` 处理 Meta webhook 的 (default 3000): a `GET /webhook` 核查 握手签名 `POST /webhook` 活动交付。 你一定要揭开这个口 公开(例如通过 ngrok)并注册 URL + `verifyToken` 在元应用程序中 配置 。 见 [`examples/whatsapp`](https://npmcn.com/package/examples/whatsapp) 全文 设出行道.

### 必需的嵌入

| 瓦尔 | 目的 |
| --- | --- |
| `WHATSAPP_ACCESS_TOKEN` | Cloud API访问令牌 (Bearer),出自Meta App ~ API设置. |
| `WHATSAPP_PHONE_NUMBER_ID` | 商业电话号码,发送消息. |
| `WHATSAPP_APP_SECRET` | 密码 `X-Hub-Signature-256` webhook 验证. |
| `WHATSAPP_VERIFY_TOKEN` | Token在GET核查握手时回放. |

## 能力

| 能力 | 支助 | 页:1 |
| --- | --- | --- |
| `supportsStreaming` | 虚假 | WhatsApp消息不可改变;没有编辑消息API. |
| `supportsModals` | 虚假 | 云的API中没有模式表面. |
| `supportsTyping` | 虚假 | 无打入指标的API用于商业账户. |
| `supportsReactions` | 虚假 | 没有反应 API 对于商务发送消息. |

因为信息是不可改变的, `thread.stream(...)` 缓冲可移动的全部 并且发出一个单一的信息——没有逐一的信号。 呼吁 `update` 财务报告和审定财务报表 `delete` 也可以是无操作者(他们发了新信息,或者默不作声) 滴出). 这个 `defaultWhatsAppContext` 条目告诉代理人这个限制 它没有承诺"更新这个消息"

## `WhatsAppAdapterOptions` 参考文献

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `accessToken` | `string` | 所需经费 | Cloud API 访问令牌 (Bearer). |
| `phoneNumberId` | `string` | 所需经费 | 商业电话号码,发送消息. |
| `appSecret` | `string` | 所需经费 | 密码 `X-Hub-Signature-256` webhook 验证. |
| `verifyToken` | `string` | 所需经费 | Token在GET核查握手时回放. |
| `port` | `number` | `3000` | HTTP 服务器端口. |
| `path` | `string` | `"/webhook"` | 韦布克道. |
| `apiVersion` | `string` | `"v21.0"` | 图表 API 版本 . |
| `graphBaseUrl` | `string` | `"https://graph.facebook.com"` | 图表 API 基础来源 。 超乎测试. |
| `interruptEventNames` | `ReadonlySet<string>` | `undefined` | 自定义 AG- UI 事件名称被运行渲染器视为中断 . |
| `commandPrefix` | `string` | `"/"` | 主键字命令匹配的前缀 . |
| `historyStore` | `HistoryStore` | `new InMemoryHistoryStore()` | 不断的对话 - 历史持续. |
| `files` | `FileDeliveryConfig` | `{}` | 进入媒体处理配置. |

## JSX – 何为App渲染

`renderWhatsAppMessage(ir)` 下调 `@copilotkit/channels-ui` IR 到 Cloud API 载荷。 战略:

-   **0 动作** - 简单 `text` 消息(已转换为WhatsApp格式).
-   **1-3 按钮动作** • 互动 `button` 消息(重写按钮).
-   **4-10项行动** • 互动 `list` 消息(列表拾取器).
-   **\>10个动作** ^ 有编号的文本菜单(降级回放).

图像节点总是发出自己的 `image` 载荷。 Markdown 翻译为 何为App格式 : `**bold**`, (中文(简体) ), `_italic_`, (中文(简体) ), `~~strikethrough~~`, (中文(简体) ), `` `code` ``,以及 代码块。 不支持标题、表格和可点击的Markdown链接 WhatsApp——链接为纯文本.

### 经常预算

WhatsApp 上限交互式元素。 限制居住 `WA_LIMITS`数字 :

| 限制 | 数值 | 元素 |
| --- | --- | --- |
| `bodyText` | 4096 (英语) | 文本信息正文字符 |
| `replyButtons` | 3个 | 在交互式按钮消息中回复按钮 |
| `buttonTitle` | 20国 | 回复按钮标题字符 |
| `interactiveBody` | 第1024号 | 交互式信件正文字符 |
| `interactiveHeader` | 页:1 | 交互式信头字符 |
| `interactiveFooter` | 页:1 | 交互式页脚字符 |
| `listRows` | 10个 | 列表消息中横跨所有段落的行总数 |
| `rowTitle` | 24个 | 列表行标题字符 |
| `rowDescription` | 72国 | 列表行描述字符 |
| `listButton` | 20国 | 列表打开按钮标签字符 |
| `controlId` | 256号 | 交互式控制 id 字符 |

## 持久性

### ActionStore(交互还水)

发动机的 `ActionStore` (从) `@copilotkit/channels`)存储薄荷不透明标识 那个力量 `Button` 编号 : `Select` 点击处理器。 默认为内存: 进程重新启动,对旧交互消息的点击被确认但被忽略. 对于持续的互动,通过持久 `ActionStore` 改为 `createChannel({ actionStore })`。 。 。 .

### HistoryStore (对话记忆)

与Slack不同的是,WhatsApp揭露了无法读取的信息历史. 适配器维持 其本身 `HistoryStore` 并重放到 `agent.messages` 在每一个转弯。 这个 默认为 `InMemoryHistoryStore` (每次谈话最多100个信息,滴出) ) (第1行,第2行). 通过执行 `HistoryStore` 接口 :

```ts
interface HistoryStore {
  append(conversationKey: string, message: StoredMessage): Promise<void>;
  read(conversationKey: string): Promise<StoredMessage[]>;
}
```

通过它作为 `historyStore` 在适配器选项中:

```ts
whatsapp({
  // ...
  historyStore: new MyRedisHistoryStore(),
});
```

没有耐用 `HistoryStore`中,对话历史在进程重新启动时丢失.

## 图标

命令与消息文本中的主关键字相匹配(默认前缀) `/`) (中文(简体) ). 登记处理器 `bot.onCommand`数字 :

```ts
bot.onCommand("status", async ({ thread, text }) => {
  await thread.runAgent({ prompt: `Status check: ${text}` });
});
```

与Slack不同的是,WhatsApp没有本地的斜线命令表面——命令是简单的 从前缀开始的文本信息。 它们不是由适配器预过滤的 (引擎与它们相匹配),命令信息不会持续到 `HistoryStore` 在入侵。 发送命令需要序列化为代理提示 明确,如果特工需要把它们视为历史.

## 内建

-   `defaultWhatsAppTools` —— v1 空 (WhatsApp 显示没有用户目录, 所以) 没有 `lookup_user` 页:1 展开到 `tools` 未来 兼容性.
-   `defaultWhatsAppContext` - 两个上下文条目:WhatsApp格式化规则 (粗体/斜体/代码,无标题或可点击链接)和交付限制(无) 流出,不编辑消息). 展开到 `context`。 。 。 .
-   `whatsAppFormattingContext` 编号 : `whatsAppDeliveryContext` ——个别条目 如果你需要有选择地作曲.

## 工具上下文

工具接收单一共享 `ChannelToolContext` 从 `@copilotkit/channels` (单位:千美元)`{ thread, message?, user?, signal?, platform }`通过WhatsApp电源 能力 `thread` 此适配器背面的方法 :

-   `thread.getMessages()` ——当前对话的信息历史(从 `HistoryStore`),每个a `ThreadMessage` (单位:千美元)`{ user?, text, ts?, isBot? }`) (中文(简体) ).
-   `thread.postFile({ bytes, filename, title?, altText? })` ——上传并发送一个 文档(图像 ) `image` 有效载荷;其他 `document` 通过介质上载的有效载荷 (原始内容存档于2018-10-12). API.

说明: `thread.lookupUser(query)` 这是对WhatsApp的禁止 —— 云 API 显示没有 用户目录。 它总是回来 `undefined`。 。 。 .

## 运行演示

这个包是 **图书馆**。可运行的端到端演示布线 对一个真实的WhatsApp数字 住在 [`examples/whatsapp`](https://npmcn.com/package/examples/whatsapp)。 。 。 .

## V1里没有什么

-   没有信件编辑或流出( WhatsApp 信件是不可改变的)
-   24小时客户服务窗口(适配器)外没有主动留言 不执行模板消息发送; 机器人只能在 由入境用户消息打开的24小时窗口
-   没有用户目录( N)`lookupUser` 总是返回 `undefined`(中文(简体) )
-   没有 OAuth / 多数安装( 仅一个访问符)
-   持久性 `ActionStore` 财务报告和审定财务报表 `HistoryStore` 默认为内存; 动作和 历史在重新启动时过期, 除非您提供持久执行

## 出口

`whatsapp`, (中文(简体) ), `WhatsAppAdapter`· ; `WhatsAppAdapterOptions`, (中文(简体) ), `ReplyTarget`, (中文(简体) ), `WhatsAppMessageRef` (类型); `WhatsAppConversationStore`· ; `InMemoryHistoryStore`, (中文(简体) ), `HistoryStore`, (中文(简体) ), `StoredMessage` (类型); `renderWhatsAppMessage`, (中文(简体) ), `WhatsAppOutbound` (类型); `WA_LIMITS`, (中文(简体) ), `truncateText`, (中文(简体) ), `clampArray`· ; `markdownToWhatsApp`· ; `decodeInteraction`, (中文(简体) ), `conversationKeyOf`· ; `createRunRenderer`· ; `WhatsAppClient`, (中文(简体) ), `DownloadedMedia` (类型); `buildFileContentParts`, (中文(简体) ), `AgentContentPart`, (中文(简体) ), `FileDeliveryConfig` (类型); `defaultWhatsAppTools`· ; `defaultWhatsAppContext`, (中文(简体) ), `whatsAppFormattingContext`, (中文(简体) ), `whatsAppDeliveryContext`。 。 。 .

## 常见问题

### @copilotkit/channels-whatsapp 是什么？

CopilotKit JSX频道的WhatsApp Cloud API平台适配器 \(@copilotkit/channels\)\.

### 如何安装 @copilotkit/channels-whatsapp？

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

### @copilotkit/channels-whatsapp 支持 TypeScript 吗？

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

### @copilotkit/channels-whatsapp 支持 ESM 还是 CommonJS？

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

### @copilotkit/channels-whatsapp 可以商用吗？

@copilotkit/channels-whatsapp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @copilotkit/channels-whatsapp 的下载量有多少？

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

### @copilotkit/channels-whatsapp 还在维护吗？

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