@great-detail/whatsapp

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

SDK for interfacing with WhatsApp Business Platform in Typescript or Node.js using the Cloud API, hosted by Meta.

原始使用文档
文档目录14 节
  1. Installation
  2. Getting started
  3. Compatibility
  4. Migrating v8 to v9
  5. Migrating v7 to v8
  6. Usage
  7. Messaging
  8. Webhooks
  9. Templates
  10. Request Options
  11. Contributing
  12. License
  13. Contact
  14. TODO

WhatsApp Business Platform API SDK for Node.JS, Deno & Bun

npm (scoped)

The unofficial SDK for Meta's WhatsApp Business Messaging APIs - Cloud API. Originally a fork of the deprecated official SDK for Meta's WhatsApp Business Messaging APIs. Supports webhooks, phone number management, whatsapp business account management, template management, messaging, webhook subscription management.

If you find a bug or have a feature request, please open an issue. Contributions are greatly appreciated too!

See this SDK's Changelog for updates and release notes.

Installation

Install the WhatsApp Business Platform SDK:

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

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

Getting started

The primary source of documentation for this SDK is via the TypeScript type definitions and JSDoc comments included in the package. The types should get you most of the way. Also see the examples and snippets section to get started using the 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" },
});

Compatibility

This SDK is designed to be compatible with the Cloud API API. Some fields used by the On-Premises API may be included, however, no on-premises-only functionality is implemented.

SDKCloud API
v8.xv23

Whilst the SDK may work with alternative versions of the Graph API, it is designed to work with the above. If you find any compatibility issues, please report them via GitHub Issues.

See this SDK's Changelog for updates and release notes.

  • Tested on NodeJS LTS Versions: v22, v24,
  • Tested on Deno LTS Versions: v2.4,
  • Tested on Bun Versions: v1.2.

Additional NodeJS versions may also work, however, automated testing requires NodeJS' test suite, which was introduced in v21. Other versions of Deno/Bun may also work, regardless of NodeJS polyfill support - uses SubtleCrypto.

Migrating v8 to v9

v9 of this SDK increased the minimum supported NodeJS to v22, alongside an update to ky that required this update.

Some request override options may have changed in-line with the options in ky - see the ky v2 release changelog for more information on which options have changed: https://github.com/sindresorhus/ky/releases/tag/v2.0.0.

Migrating v7 to v8

v8 of this SDK increased the minimum supported NodeJS version to v20.19.0, alongside the release of support for require() with ESM. This also coincides with NodeJS v18 reaching EOL, thus making the minimum LTS NodeJS version v20.

This update to the minimum supported NodeJS version allows us to greatly decrease the bundle size due to releasing ESM-only builds. Consumers in a CJS environment should still be able to use the library as before.

v8 also removes the CLI aspect of this package. This change comes as the CLI aspect of this SDK hasn't been updated since early development and support for later functionality was not added. This too allows for a reduction in bundle size.

v8 of this SDK also updates the default Meta Graph API version to v23.0 - whilst this update should maintain compatibility, to remain on the previous Graph API version (v20.0) update instantiation of this client as follows:

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

Usage

See the following usage examples for usage. Included in the source code and editor integrations, TypeScript type definitions and JSDoc comments may provide additional context and information.

Messaging

Create a Status Message:

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

Create a Text Message:

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

Create a Template Message:

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

Create an Interactive Message:

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

Upload Media Files:

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

Get a Media File's Download URL:

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

Download Media Files:

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

Webhooks

Listen for Webhook Requests with Express:

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

Listen for Webhook Requests with Fastify:

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

Listen for Webhook Requests with Oak:

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

Templates

Create a Template:

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

Request Options

Under the hood, this SDK uses ky as a fetch wrapper. This means that all of the quality-of-life features provided by ky can be available to this SDK, including: retries, hooks, auto-throwing on HTTP errors, etc. A number of these features are used under-the-hood already, e.g. auto-throwing on HTTP errors.

v9 of this SDK updates ky to v2 - this update has some changes to the request options - see the ky v2 release changelog for more information: https://github.com/sindresorhus/ky/releases/tag/v2.0.0.

Request Retries:

  • Default retries: 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)
  },
});

Contributing

Contributions are greatly appreciated - especially surrounding API updates and type correction! To get started:

  1. Fork the repository and create your branch from main.
  2. Write clear, well-documented code and include tests where possible.
  3. Open a pull request describing your changes and referencing any related issues.

Please review our Code of Conduct before submitting.

If you find a bug or have a feature request, please open an issue.

License

MIT © Great Detail Ltd

Originally forked from the official WhatsApp SDK created by Rashed Talukder.

Contact

This SDK was originally forked from the deprecated official SDK and is now maintained by Great Detail.

Great Detail Ltd: https://greatdetail.com [email protected]

TODO

There are a number of features supported by the WhatsApp Business Cloud API and WhatsApp Business Management API that are yet to be implemented in this SDK. Please feel free to contribute via a Pull Request, or note your interest in particular features by creating an issue for it.

  • Interactive Message Types,
  • Template Message Types,
  • Template Management,
  • Button Message Types,
  • Flow Message Types,
  • List Message Types,
  • WABA Webhook Subscription Management,
  • WABA Extended Credit Management,
  • WABA Phone Number Management,
  • WABA System User Management?

版本与发布记录

@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 for interfacing with WhatsApp Business Platform in Typescript or Node.js using the Cloud API, hosted by 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 和提交记录判断。