https://github.com/great-detail/whatsapp-nodejs-sdk
NodeJS SDK and CLI for Meta's WhatsApp Business Messaging APIs - Cloud API
https://github.com/great-detail/whatsapp-nodejs-sdk
cli facebook meta sdk sdk-nodejs whatsapp
Last synced: 8 months ago
JSON representation
NodeJS SDK and CLI for Meta's WhatsApp Business Messaging APIs - Cloud API
- Host: GitHub
- URL: https://github.com/great-detail/whatsapp-nodejs-sdk
- Owner: great-detail
- Created: 2023-09-29T09:09:21.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-28T08:08:17.000Z (9 months ago)
- Last Synced: 2025-05-28T09:21:09.514Z (9 months ago)
- Topics: cli, facebook, meta, sdk, sdk-nodejs, whatsapp
- Language: TypeScript
- Homepage:
- Size: 3.97 MB
- Stars: 5
- Watchers: 0
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Node.js SDK for WhatsApp Business Platform APIs
An 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](https://github.com/WhatsApp/WhatsApp-Nodejs-SDK).
[![npm (scoped)][]][sdk-npmjs] [![Lint, Format, Test & Build][]][sdk-ci]
[npm (scoped)]: https://img.shields.io/npm/v/%40great-detail/whatsapp
[sdk-npmjs]: https://www.npmjs.com/package/@great-detail/whatsapp
[Lint, Format, Test & Build]:
https://github.com/great-detail/WhatsApp-Nodejs-SDK/actions/workflows/nodejs.ci.yml/badge.svg
[sdk-ci]:
https://github.com/great-detail/WhatsApp-Nodejs-SDK/actions/workflows/nodejs.ci.yml
## Getting started
**ESM Import**:
```ts
import Client from "@great-detail/whatsapp";
```
**CJS Import**:
```ts
const Client = require("@great-detail/whatsapp").default;
```
**Usage**:
```typescript
const sdk = new Client();
const message = await sdk.message.createMessage({
phoneNumberID: "123...809",
to: "1234567890",
type: "text",
text: {
body: "Hello",
},
request: {
headers: {
Authorization: "Bearer ...",
},
},
});
```
## Installation
Install the WhatsApp Business Platform SDK:
```bash
# NPM:
npm install @great-detail/whatsapp
# Yarn:
yarn add @great-detail/whatsapp
# PNPM:
pnpm add @great-detail/whatsapp
```
## CLI Usage
```bash
export WHATSAPP_ACCESS_TOKEN=""
export WHATSAPP_PHONE_NUMBER_ID=""
# NPM / Yarn / PNPM
npx @great-detail/whatsapp ...
yarn dlx @great-detail/whatsapp ...
pnpx @great-detail/whatsapp ...
# Send a Text Message
# TODO: Re-add with updated SDK
npx @great-detail/whatsapp message send text "" --body="Hello, World!"
# Note: may be a Phone Number ID - it may not always be the phone number itself.
# Send an Image Message
# TODO: Re-add with updated SDK
# npx @great-detail/whatsapp message send image "" --media-id=""
# Use --filename="..." to set the filename of the image.
# Use --caption="..." to set a caption on the image.
# Upload a Media File
npx @great-detail/whatsapp media upload --mime-type="" < ""
# Get a Media File's URL
npx @great-detail/whatsapp media get-url ""
# Note: With WHATSAPP_PHONE_NUMBER_ID set, the request will check if the media
# is available for that phone number. To prevent this check, unset the env var
# or add --phone-number-id="" to the command.
# Download a Media File
npx @great-detail/whatsapp media download "" > ""
```
## Compatibility
This SDK is designed to be compatible with the Cloud API API.
| SDK | Cloud API | NodeJS |
| :--- | :-------: | -----: |
| v7.x | v20 | v18+ |
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](https://github.com/great-detail/WhatsApp-Nodejs-SDK/issues).
**Tested on NodeJS**: `v21`, `v22`, `v23`.
Additional NodeJS versions may also work, however, automated testing requires
NodeJS' test suite, which was introduced in `v21`.
## TODO
There are a number of features supported by the WhatsApp Business Cloud 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.
- [ ] Button Message Types.
- [ ] Flow Message Types.
- [ ] List Message Types.
- [x] WABA Webhook Subscription Management.
- [ ] WABA Extended Credit Management.
- [x] WABA Phone Number Management.
- [ ] WABA System User Management?
- [ ] Considering Authentication usage improvements.
## License
The WhatsApp Business Platform Node.js SDK for the Cloud API is Meta Platforms
licensed, as found in the LICENSE file.