# @chat-adapter/messenger 中文文档

规范地址：https://npmcn.com/package/%40chat-adapter/messenger/

版本：4\.44\.0
npm 元数据更新时间：2026-11-02T14:55:46.915Z
中文译文更新时间：2026-11-09T11:23:06.092Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40chat-adapter/messenger
原文对照：https://npmcn.com/package/%40chat-adapter/messenger/?lang=original
项目主页：https://chat-sdk.dev/adapters/official/messenger
源码仓库：https://github.com/vercel/chat

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

- 包体积（解压后）：112 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-05-07T21:18:46.074Z
- 最新版本发布：2026-11-02T14:55:46.563Z
- 近 30 天下载量：102331（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

Chat SDK 的 Facebook 信使适配器 — 发送 API webhooks, 模板和快速回复

## 安装

```sh
npm install @chat-adapter/messenger
```

也可以使用：`pnpm add @chat-adapter/messenger`、`yarn add @chat-adapter/messenger`、`bun add @chat-adapter/messenger`

## README

[![Facebook Messenger adapter for Chat SDK](https://chat-sdk.dev/en/adapters/official/messenger/og)](https://chat-sdk.dev/adapters/official/messenger)

# @ 聊天适应器/ 信使

> npm 软件包 : [`@chat-adapter/messenger`](https://www.npmjs.com/package/@chat-adapter/messenger)

[![Agent Stack](https://img.shields.io/badge/Agent%20Stack-000?style=flat-square&logo=vercel&logoColor=FFF&labelColor=000&color=000)](https://vercel.com/kb/agent-stack) [![MIT License](https://img.shields.io/badge/License-MIT-000?style=flat-square&logo=opensourceinitiative&logoColor=white&labelColor=000&color=000)](https://npmcn.com/package/LICENSE)

Facebook 通讯器适配器 [聊天SDK](https://chat-sdk.dev/),使用 [信使平台 API](https://developers.facebook.com/docs/messenger-platform)。 。 。 .

联合国 [聊天-sdk.dev/适应者/官员/送信员](https://chat-sdk.dev/adapters/official/messenger) 指南: [vercel.com/kb/chat-sdk (英语)](https://vercel.com/kb/chat-sdk)

> 建为 Instagram 直接信件吗 ? 使用 [`@chat-adapter/instagram`](https://chat-sdk.dev/adapters/official/instagram) 换句话说 它通过Instagram API与Instagram Login连接,不需要Facebook页面.

## 安装

```bash
pnpm add @chat-adapter/messenger
```

## 带CLI的脚手架

要用这个适配器预选的 新的Messetbot 脚手架:

```bash
npx create-chat-sdk@latest my-bot --adapter messenger memory
```

访问 [适配器目录](https://chat-sdk.dev/adapters) 见其他官方和供应商官方适配器.

## 使用量

```typescript
import { Chat } from "chat";
import { createMessengerAdapter } from "@chat-adapter/messenger";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    messenger: createMessengerAdapter(),
  },
});

bot.onDirectMessage(async (thread, message) => {
  await thread.post("Hello from Messenger!");
});
```

使用时 `createMessengerAdapter()` 证书由环境变量自动检测.

## Facebook 通讯器设置

### 1\. 创建 Meta 应用程序

1.  转到 [开发者. facebook.com/apps 页面存档备份,存于互联网档案馆](https://developers.facebook.com/apps)
2.  点击 **创建 App**
3.  选择使用大小写 **"在Meta的"信使"上与顾客的接触"**
4.  输入您的应用程序名称并联系电子邮件, 然后创建该应用程序
5.  转到 **App > App 设置 > 基础** 复制您的 **应用程序保密** 这变成了 `FACEBOOK_APP_SECRET`

### 2\. 创建Facebook页面

您的信使机器人需要一个Facebook页面来发送和接收消息 。 如果你没有的话:

1.  最简单的做法是建立一个 **Facebook 企业简介** 第一个
2.  然后在该商务简介下创建一页
3.  注意 Page 名称 - 用户会发送此 Page 与您的 bot 交互

### 3\. 配置信使 API

1.  在你的Meta应用仪表板,去 **使用大小写**
2.  查找 **"在Meta的"信使"上与顾客的接触"** 并单击 **自定义**
3.  然后打开 **通讯员 API 设置**

#### 配置网点

1.  下 **配置网点**,单击 **添加回调 URL**
2.  输入您的 Webhook URL : `https://your-domain.com/api/webhooks/messenger`
3.  输入 a **校验托肯** ——这是您创建的秘密字符串(它变成了 `FACEBOOK_VERIFY_TOKEN`(中文(简体) )
4.  点击 **校验并保存**
5.  校验后,单击 **添加订阅** 并能够:
    -   `messages`
    -   `messaging_postbacks`
    -   `messaging_reactions`
    -   `message_deliveries`
    -   `message_reads`

#### 生成一个页面访问键

1.  下 **生成访问令牌**,单击 **添加或删除页面**
2.  您的页面应该填充—— 选择您创建的页面
3.  提示时指定标准权限
4.  点击 **生成托肯**
5.  复制代币——变成 `FACEBOOK_PAGE_ACCESS_TOKEN`

## 环境变量

```bash
FACEBOOK_APP_SECRET=...              # App secret from App Settings > Basic
FACEBOOK_PAGE_ACCESS_TOKEN=...       # Generated Page access token
FACEBOOK_VERIFY_TOKEN=...            # User-defined webhook verification secret
FACEBOOK_BOT_USERNAME=...            # Optional, defaults to "messenger-bot"
FACEBOOK_API_URL=...                 # Optional, override the Meta Graph API base URL
```

## Webhook 设置

信使使用两个网钩机制:

1.  **核查握手** (GET)——梅塔发送a `hub.verify_token` 挑战,必须与您的 `FACEBOOK_VERIFY_TOKEN`。 。 。 .
2.  **事件交付** (POST)——接收的信息,反应和后退,通过 `X-Hub-Signature-256`。 。 。 .

```typescript
// Next.js App Router example
import { bot } from "@/lib/bot";

export async function GET(request: Request) {
  return bot.webhooks.messenger(request);
}

export async function POST(request: Request) {
  return bot.webhooks.messenger(request);
}
```

## 特征

### 通讯

| 特性 | 支助 |
| --- | --- |
| 邮件 | 对 |
| 编辑信件 | 否(信使限制) |
| 删除信件 | 否(信使限制) |
| 流线 | 缓冲(累积后发送) |
| 打字指标 | 对 |
| 标记为已读 | 对 |

### 丰富内容

| 特性 | 支助 |
| --- | --- |
| 卡片格式 | 一般/按钮模板 |
| 按钮 | 是(每封信最多3封) |
| 链接按钮 | 是( web url) |
| 选择菜单 | 没有 |
| 表格 | 文本倒转 |
| 字段 | 文本倒转 |
| 纸牌中的图像 | 是( 遗传模板) |
| 模块 | 没有 |

### 对话

| 特性 | 支助 |
| --- | --- |
| 反应 | 只接收 |
| 打字指标 | 对 |
| 模式 | 是(仅限DM平台) |
| 后退 | 对 |

### 入境附件

输入附件 URL 作为 `attachment.url`。适配器的 `fetchData` 函数只从 Meta 下载媒体 `fbsbx.com` 财务报告和审定财务报表 `fbcdn.net` 主机,拒绝私有和内部地址(包括之后) 重定向),将响应限制在25 MB,30秒后出局. 外部倒计时和链接共享 URL 保存但拒绝之前 网络请求.

### 读取收据

使用 `thread.markAsRead()` 在信件处理器中发送信使 `mark_seen` 发送器动作 :

```typescript
await thread.markAsRead();
```

信使将这个动作应用到对话中看到的状态而不是单个消息,即使你传递了消息或消息ID.

### 信件历史

| 特性 | 支助 |
| --- | --- |
| 获取信件 | 只发送缓存信件 |
| 获取线索信息 | 对 |

## 交互式消息

卡片元素被自动转换为Messer模板 :

-   **通用模板** ——卡有卡时使用 `title` 或者说 `imageUrl`。支持最多3个按钮.
-   **按钮模板** ——卡片有文本内容和按钮但没有标题/图像时使用. 最大640个字符.
-   **文本倒转** ——当卡片包含不支持的元素(表格,选择菜单)或超过限制时使用.

模板限制 :

-   每个模板最大3个按钮
-   按钮标题限制为 20 个字符( 有椭圆形)
-   字幕限制为80个字符
-   按键模板文本限制为 640 个字符

## 线索标识格式

```
messenger:{recipientId}
```

示例 `messenger:27161130920158013`

## AI 编码代理

如果您使用OpenAI Codex, Claude Code, 或 Cursor 等AI编码代理, 在写入代码前安装 Chat SDK 技能, 使其了解 SDK API, 适配器模式, 以及项目常规 .

```bash
npx skills add vercel/chat
```

技术参考文献 `node_modules/chat/docs`,加上已发布的软件包中的适配器指南和启动模板.

您也可以安装 [Vercel 插件](https://vercel.com/docs/agent-resources/vercel-plugin) 包括Chat SDK技术与专家代理、代理斜线指令

```bash
npx plugins add vercel/vercel-plugin
```

插件是可选的;单是技能就足以用Chat SDK来构建.

关于可代理阅读的文件,见 [聊天- sdk.dev/llms.txt](https://chat-sdk.dev/llms.txt) (页数索引)或 [聊天- sdk.dev/llms- full.txt](https://chat-sdk.dev/llms-full.txt) (全文).

## 许可证

麻省理工学院

## 常见问题

### @chat-adapter/messenger 是什么？

Chat SDK 的 Facebook 信使适配器 — 发送 API webhooks, 模板和快速回复

### 如何安装 @chat-adapter/messenger？

在项目目录运行 npm install @chat-adapter/messenger，或使用 pnpm add / yarn add / bun add。

### @chat-adapter/messenger 支持 TypeScript 吗？

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

### @chat-adapter/messenger 支持 ESM 还是 CommonJS？

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

### @chat-adapter/messenger 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chat-adapter/messenger 可以商用吗？

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

### @chat-adapter/messenger 的下载量有多少？

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

### @chat-adapter/messenger 还在维护吗？

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