# @great-detail/whatsapp 中文文档

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

版本：9\.2\.0
npm 元数据更新时间：2026-09-22T11:42:33.410Z
中文译文更新时间：2026-11-17T00:10:28.008Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.1 MB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2023-10-03T12:45:02.804Z
- 最新版本发布：2026-09-22T11:42:33.067Z
- 近 30 天下载量：16583（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：146（近 12 个月 11 个）

## 中文简介

SDK用于在Typescript或Node.js中使用Cloud API与WhatsApp Business平台的接口,由Meta主持.

## 安装

```sh
npm install @great-detail/whatsapp
```

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

## README

# 节点的WhatsApp Business 平台 API SDK.JS, Deno & Bun

[![npm (scoped)](https://img.shields.io/npm/v/%40great-detail/whatsapp)](https://www.npmjs.com/package/@great-detail/whatsapp)

非官方SDK为Meta's WhatsApp Business Message APIs - Cloud API所提供. 本来是叉子 [meta's WhatsApp Business Message APIs被贬值的官方 SDK](https://github.com/WhatsApp/WhatsApp-Nodejs-SDK)。 。 。 . 支持 Webhoks, 电话号码管理, 什么应用商业账户 管理,模板管理,信息传递,webhook订阅管理.

如果您找到错误或有特性请求, 请 [打开一个问题](https://github.com/great-detail/WhatsApp-JS-SDK/issues)。 。 。 . [捐款](https://npmcn.com/package/%40great-detail/whatsapp/#readme-contributing) 为: **非常厉害** 谢谢!

看这个SDK的 [更改日志](https://github.com/great-detail/WhatsApp-JS-SDK/blob/main/CHANGELOG.md) 用于更新和发布注释.

## 安装

安装 WhatsApp 商业平台 SDK :

```bash
# NPM:
npm install @great-detail/whatsapp
# ^ or use PNPM, Yarn, Bun

# Deno:
deno add npm:@great-detail/whatsapp
```

## 开始

此 SDK 文档的主要来源是通过 TypeScript 类型 定义和联合来文文件的评论已纳入一揽子计划。 类型应该让你 大部分时间都是这样 另见 [示例和片断部分](https://npmcn.com/package/%40great-detail/whatsapp/#readme-usage) 获取 开始使用SDK.

```ts
import Client from "@great-detail/whatsapp"; // for ESM environments
// require("@great-detail/whatsapp"); // for CJS environments
// import Client from "npm:@great-detail/whatsapp"; // for Deno

// Instantiate the SDK Client
const sdk = new Client({
  request: {
    headers: { Authorization: "Bearer ..." },
  },
});

// Use it!
const message = await sdk.message.createMessage({
  phoneNumberID: "123...809",
  to: "1234567890",
  type: "text",
  text: { body: "Hello" },
});
```

## 兼容性

这个SDK的设计与Cloud API API兼容. 使用的一些字段 编辑 [预设 API](https://developers.facebook.com/docs/whatsapp/on-premises/sunset/) 不过,可能包括不执行仅设前提的功能.

| SDK 软件 | 云类 API |
| :-- | --: |
| v8.x (中文(简体) ) | 页:1 |

虽然SDK可能与Graph API的替代版本相配合,但它是 旨在配合上述工作。 如果你发现任何兼容性问题,请 报告通过 [GitHub 问题](https://github.com/great-detail/WhatsApp-JS-SDK/issues)。 。 。 .

看这个SDK的 [更改日志](https://github.com/great-detail/WhatsApp-JS-SDK/blob/main/CHANGELOG.md) 用于更新和发布注释.

-   **在节点JS LTS 版本上测试**数字 : `v22`, (中文(简体) ), `v24`, (中文(简体) ),
-   **在 Deno LTS 版本上测试**数字 : `v2.4`, (中文(简体) ),
-   **在 Bun 版本上测试**数字 : `v1.2`。 。 。 .

额外的节点JS版本也可以工作,但需要自动测试 节点JS的测试套房, 引入于 `v21`. Deno/Bun的其他版本 也可以工作,无论节点JS多填充支持如何——使用SubtleCrypto.

## 将 v8 移动到 v9

此 SDK 中的 v9 将支持的最小节点JS 增加到 v22, 并加一个 更新到 [凯](https://github.com/sindresorhus/ky) 这需要更新.

某些请求覆盖选项可能已随 KY 中的选项在行中更改 - 关于选项的更多信息,请参见 ky v2 发布更改日志 已更改 : [https://github.com/sindresorhus/ky/releases/tag/v2.0.0 (英语)](https://github.com/sindresorhus/ky/releases/tag/v2.0.0)。 。 。 .

## 移动 v7 到 v8

此 SDK 中的 v8 将支持的最小节点JS 版本增加至 v20.19.0, 与解除对 [`require()` 采用无害环境管理](https://github.com/nodejs/node/releases/tag/v20.19.0)。 。 。 . 这也与NodeJS v18 到达EOL同时进行,从而使得最小LTS 节点JS版本v20.

这个更新到最小支持的 NodeJS 版本可以让我们大大 减少捆绑体积,因为释放了仅限无害环境管理的建筑。 CJS中的消费者 环境应 [仍然可以像以前一样使用图书馆](https://github.com/nodejs/node/releases/tag/v20.19.0)。 。 。 .

v8 也删除了此软件包的 CLI 方面 。 这变化是随着CLI而来 自早期开发和支持以来,SDK的这一方面一直没有更新 后来的功能没有被添加. 这样也可以减少捆绑量 尺寸.

此 SDK 的 v8 还更新了默认的 Meta Graph API 版本 `v23.0` - 说吧 虽然该更新应保持兼容性,但仍保留在以前的 图表 API 版本 (`v20.0`更新对该客户端的即时描述如下:

```ts
// To remain on the previous Graph API version:
const sdk = new Client({
  // Add this line to the instantiation options:
  graphVersion: "v20.0",
  // ...
});
```

## 使用量

参见以下用法示例. 列入源代码和 编辑器集成、TypeScript类型定义和JSDoc评论可能提供 其他背景和信息.

### 通讯

**创建状态信件**数字 :

```ts
const message = await sdk.message.createStatus({
  phoneNumberID: "123...809",
  message_id: "...",
  status: "read",
  typing_indicator: { type: "text" },
});
```

**创建文本消息**数字 :

```ts
const message = await sdk.message.createMessage({
  phoneNumberID: "123...809",
  to: "1234567890",
  type: "text",
  text: { body: "Hello" },
});
```

**创建模板信件**数字 :

```ts
const message = await sdk.message.createMessage({
  phoneNumberID: "123...809",
  to: "1234567890",
  type: "template",
  template: {
    name: "test_1",
    language: { code: "en_US" },
    components: [
      {
        type: "body",
        parameters: [
          // Add some parameters:
          { type: "text", text: "Example" },
          {
            type: "currency",
            currency: {
              fallback_value: "£100",
              code: "GBP",
              amount_1000: 100_000,
            },
          },
          {
            type: "date_time",
            date_time: {
              fallback_value: "2026-01-01",
            },
          },
        ],
      },
    ],
  },
});
```

**创建交互式信件**数字 :

谢谢@lcneves!

```ts
const message = await sdk.message.createMessage({
  phoneNumberID: "123...809",
  to: "1234567890",
  type: MessageType.Interactive,
  interactive: {
    type: "button",
    body: {
      text: "Hello",
    },
    action: {
      buttons: [
        {
          type: "reply",
          reply: {
            id: "button1",
            title: "Button 1",
          },
        },
        {
          type: "reply",
          reply: {
            id: "button2",
            title: "Button 2",
          },
        },
      ],
    },
  },
});
```

```ts
const message = await sdk.message.createMessage({
  phoneNumberID: "123...809",
  to: "1234567890",
  type: MessageType.Interactive,
  interactive: {
    type: "cta_url",
    body: {
      text: "Hello",
    },
    action: {
      name: "cta_url",
      parameters: {
        display_text: "Open Link",
        url: "https://example.com",
      },
    },
  },
});
```

```ts
const message = await sdk.message.createMessage({
  phoneNumberID: "123...809",
  to: "1234567890",
  type: MessageType.Interactive,
  interactive: {
    type: "list",
    body: {
      text: "Hello",
    },
    action: {
      button: "View Options",
      sections: [
        {
          title: "Section 1",
          rows: [
            {
              id: "option1",
              title: "Option 1",
              description: "This is option 1",
            },
            {
              id: "option2",
              title: "Option 2",
              description: "This is option 2",
            },
          ],
        },
        {
          title: "Section 2",
          rows: [
            {
              id: "option3",
              title: "Option 3",
              description: "This is option 3",
            },
            {
              id: "option4",
              title: "Option 4",
              description: "This is option 4",
            },
          ],
        },
      ],
    },
  },
});
```

**上传媒体文件**数字 :

```ts
import fs from "fs";
const fileBuffer = fs.readFileSync("<FILE_PATH>");
const result = await sdk.media.upload({
  phoneNumberID: "123...809",
  mimeType: "<MIME_TYPE>",
  file: fileBuffer,
});
```

**获取媒体文件下载 URL**数字 :

```ts
const result = await sdk.media.upload({
  phoneNumberID: "123...809",
  mediaID: "<MEDIA_ID>",
});
```

**下载媒体文件**数字 :

```ts
import fs from "fs";
const result = await sdk.media.download("<MEDIA_URL>");
const file = await result.arrayBuffer();
fs.writeFileSync("<FILE_PATH>", Buffer.from(file));
```

### 网络呼号

**随快递一起收听 Webhook 请求**数字 :

```ts
// Registration requests:
app.get("/path/to/webhook", async (req, res) => {
  const reg = await sdk.webhook.register({
    method: request.method,
    query: req.query,
    body: req.body,
    headers: req.headers,
  });
  // DIY: Check the reg.verifyToken value
  if (reg.verifyToken !== "abcd") {
    return res.end(reg.reject());
  }
  return res.end(reg.accept());
});

// Event Notification requests:
app.use(express.raw()); // Important <-
app.post("/path/to/webhook", async (req, res) => {
  const event = sdk.webhook.eventNotification({
    method: request.method,
    query: req.query,
    body: req.body.toString(),
    headers: req.headers,
  });
  // DIY: Load the Meta App Secret
  event.verifySignature("abcd-app-secret");
  // Non-200 status codes will be retried
  // You may want to use the dreaded "successful error"
  if (someFailedCondition) {
    res.status(400);
    return res.end();
  }
  return res.end(event.accept());
});
```

**使用快捷键收听 Webhook 请求**数字 :

```ts
// Registration requests:
fastify.route({
  method: "GET",
  url: "/path/to/webhook",
  handler: (request, reply) => {   *
    const reg = await sdk.webhook.register({
      method: request.method,
      query: request.query,
      body: undefined,
      headers: request.headers,
    });
    // DIY: Check the reg.verifyToken value
    if (reg.verifyToken !== "abcd") {
      return reply.send(reg.reject());
    }
    return reply.send(reg.accept());
  }
});

// Event Notification requests:
// See: https://github.com/fastify/fastify/issues/707#issuecomment-817224931
fastify.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => {
  done(null, body);
});

fastify.route({
  method: "POST",
  url: "/path/to/webhook",
  handler: (request, reply) => {
    // This SDK handles inbound webhook requests from a string for signature verification
    assert(Buffer.isBuffer(request.body) || typeof request.body === "string");
    const body = request.body.toString();

    const event = sdk.webhook.eventNotification({
      method: request.method,
      query: request.query,
      body,
      headers: request.headers,
    });
    // DIY: Load the Meta App Secret
    event.verifySignature("abcd-app-secret");
    // Non-200 status codes will be retried
    // You may want to use the dreaded "successful error"
    if (someFailedCondition) {
      return reply.code(400).send();
    }
    return reply.send(event.accept());
  }
});
```

**与橡树一起聆听 Webhook 请求**数字 :

```ts
// Registration requests:
router.get("/path/to/webhook", async (context) => {
  const reg = await sdk.webhook.register({
    method: context.request.method,
    query: Object.fromEntries(context.request.url.searchParams),
    body: undefined,
    headers: Object.fromEntries(context.request.headers),
  });
  // DIY: Check the reg.verifyToken value
  if (reg.verifyToken !== "abcd") {
    context.response.body = reg.reject();
    return;
  }
  context.response.body = reg.accept();
});

// Event Notification requests:
router.post("/path/to/webhook", async (context) => {
  const body = await context.request.body({ type: "text" }).value;
  const event = sdk.webhook.eventNotification({
    method: context.request.method,
    query: Object.fromEntries(context.request.url.searchParams),
    body,
    headers: Object.fromEntries(context.request.headers),
  });
  // DIY: Load the Meta App Secret
  event.verifySignature("abcd-app-secret");
  // Non-200 status codes will be retried
  // You may want to use the dreaded "successful error"
  if (someFailedCondition) {
    context.response.status = 400;
    context.response.body = "";
    return;
  }
  context.response.body = event.accept();
});
```

### 模板

**创建模板**数字 :

```ts
const template = await sdk.template.create(
  "123...809", // WABA ID
  {
    parameter_format: "NAMED",
    components: [
      {
        type: "BODY",
        text: "Hello, {{name}}!",
        example: {
          body_text_named_params: [
            {
              param_name: "name",
              example: "John",
            },
          ],
        },
      },
    ],
  },
);
```

## 请求选项

盖下,这个SDK用 [凯](https://github.com/sindresorhus/ky) 作为 获取包装。 这意味着: k 可以为 SDK 提供, 包括: 重试、 钩子、 自动推入 HTTP 错误等. 其中一些特征已经使用在 " 下 " , 例如,在HTTP错误上自动投放.

此 SDK 的 v9 更新 ky 到 v2 - 此更新对请求有一些更改 选项 - 更多信息请参见 ky v2 释放更改日志 : [https://github.com/sindresorhus/ky/releases/tag/v2.0.0 (英语)](https://github.com/sindresorhus/ky/releases/tag/v2.0.0)。 。 。 .

**请求检索**数字 :

-   默认重试 : 3

```ts
const sdk = new Client({
  request: {
    // ...
    retry: 5, // E.g. 5 retries (6 requests total)
  },
});

// or at a method level
const message = await sdk.message.createMessage({
  phoneNumberID: "123...809",
  to: "1234567890",
  type: "text",
  text: { body: "Hello" },
  request: {
    // ...
    retry: 5, // E.g. 5 retries (6 requests total)
  },
});
```

## 捐款

捐款为: **非常厉害** 赞赏 - 特别是周围的 API 更新 输入校正! 要开始 :

1.  **叉头** 创建您的分支 `main`。 。 。 .
2.  **写清楚、文件齐全的代码** 并尽可能包括测试.
3.  **打开拉动请求** 描述您的更改并引用任何相关的 问题.

请审查一下我们 [行为守则](https://github.com/great-detail/WhatsApp-JS-SDK/blob/main/CODE_OF_CONDUCT.md) 在提交之前.

如果您找到错误或有特性请求, 请 [打开一个问题](https://github.com/great-detail/WhatsApp-JS-SDK/issues)。 。 。 .

## 许可证

[麻省理工学院](https://github.com/great-detail/WhatsApp-JS-SDK/blob/main/LICENSE)

最初来自官方WhatsApp SDK由拉希德·塔卢克德所创造.

### 联系人

这个SDK原本是从 [贬值的官方 SDK](https://github.com/WhatsApp/WhatsApp-Nodejs-SDK) 财务报告和审定财务报表 现在由"大细节"维护.

**大细节有限公司**数字 : [https://greatdetail.com (中文(简体) )](https://greatdetail.com/) [信息@ greatdetail.com](mailto:info@greatdetail.com)

## 开始

"WhatsApp Business Cloud API"和"WhatsApp Business Cloud API"支持了一些功能 在SDK中尚未执行的WhatsApp Business Management API. 请随意通过Pull Experience 或注解你的兴趣 给它制造出一个问题.

-   [x] 交互式信件类型,
-   [x] 模板信件类型,
-   [x] 模板管理,
-   [x] 按钮消息类型,
-   [ ] 流出信件类型,
-   [ ] 列出信件类型,
-   [x] WABA Webhook 订阅管理,
-   [ ] WABA 扩大信贷管理,
-   [x] WABA电话管理,
-   [ ] WABA系统用户管理?

## 常见问题

### @great-detail/whatsapp 是什么？

SDK用于在Typescript或Node\.js中使用Cloud API与WhatsApp Business平台的接口,由Meta主持\.

### 如何安装 @great-detail/whatsapp？

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

### @great-detail/whatsapp 支持 TypeScript 吗？

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

### @great-detail/whatsapp 支持 ESM 还是 CommonJS？

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

### @great-detail/whatsapp 需要什么版本的 Node\.js？

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

### @great-detail/whatsapp 可以商用吗？

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

### @great-detail/whatsapp 的下载量有多少？

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

### @great-detail/whatsapp 还在维护吗？

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

