@great-detail/whatsapp

中文文档
9.2.0发布于 2026/09/22MITTypeScriptES Module构建来源已验证近 30 天下载 1.7万

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

中文使用文档
文档目录14 节
  1. 安装
  2. 开始
  3. 兼容性
  4. 将 v8 移动到 v9
  5. 移动 v7 到 v8
  6. 使用量
  7. 通讯
  8. 网络呼号
  9. 模板
  10. 请求选项
  11. 捐款
  12. 许可证
  13. 联系人
  14. 开始

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

npm (scoped)

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

如果您找到错误或有特性请求, 请 打开一个问题。 。 。 . 捐款 为: 非常厉害 谢谢!

看这个SDK的 更改日志 用于更新和发布注释.

安装

安装 WhatsApp 商业平台 SDK :

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

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

开始

此 SDK 文档的主要来源是通过 TypeScript 类型 定义和联合来文文件的评论已纳入一揽子计划。 类型应该让你 大部分时间都是这样 另见 示例和片断部分 获取 开始使用SDK.

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 不过,可能包括不执行仅设前提的功能.

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

虽然SDK可能与Graph API的替代版本相配合,但它是 旨在配合上述工作。 如果你发现任何兼容性问题,请 报告通过 GitHub 问题。 。 。 .

看这个SDK的 更改日志 用于更新和发布注释.

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

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

将 v8 移动到 v9

此 SDK 中的 v9 将支持的最小节点JS 增加到 v22, 并加一个 更新到 凯 这需要更新.

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

移动 v7 到 v8

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

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

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

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

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

使用量

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

通讯

创建状态信件数字 :

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

创建文本消息数字 :

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

创建模板信件数字 :

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!

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",
          },
        },
      ],
    },
  },
});
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",
      },
    },
  },
});
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",
            },
          ],
        },
      ],
    },
  },
});

上传媒体文件数字 :

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数字 :

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

下载媒体文件数字 :

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 请求数字 :

// 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 请求数字 :

// 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 请求数字 :

// 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();
});

模板

创建模板数字 :

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用 凯 作为 获取包装。 这意味着: k 可以为 SDK 提供, 包括: 重试、 钩子、 自动推入 HTTP 错误等. 其中一些特征已经使用在 " 下 " , 例如,在HTTP错误上自动投放.

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

请求检索数字 :

  • 默认重试 : 3
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. 打开拉动请求 描述您的更改并引用任何相关的 问题.

请审查一下我们 行为守则 在提交之前.

如果您找到错误或有特性请求, 请 打开一个问题。 。 。 .

许可证

麻省理工学院

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

联系人

这个SDK原本是从 贬值的官方 SDK 财务报告和审定财务报表 现在由"大细节"维护.

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

开始

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

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

版本与发布记录

@great-detail/whatsapp 共发布 146 个版本,首次发布于 2023/10/03;过去 12 个月发布了 11 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.2.0latest2026/09/221 个月前
9.1.1-next-20260922111803next2026/09/221 个月前
9.1.1-next-202609221109302026/09/221 个月前
9.1.1-next-202609221045012026/09/221 个月前
9.1.1-next-202609220955072026/09/221 个月前
9.1.1-next-202609220951112026/09/221 个月前

关于 @great-detail/whatsapp 的常见问题

@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 和提交记录判断。