Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/secreto31126/whatsapp-api-js
A TypeScript server agnostic Whatsapp's Official API framework
https://github.com/secreto31126/whatsapp-api-js
api bot bot-api bot-framework business-api chatbot cloud cloud-api deno javascript nodejs npm-package whatsapp whatsapp-api whatsapp-bot whatsapp-business whatsapp-business-api whatsapp-cloud whatsapp-cloud-api
Last synced: 2 days ago
JSON representation
A TypeScript server agnostic Whatsapp's Official API framework
- Host: GitHub
- URL: https://github.com/secreto31126/whatsapp-api-js
- Owner: Secreto31126
- License: mit
- Created: 2022-04-26T00:53:25.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-20T16:27:28.000Z (6 days ago)
- Last Synced: 2024-09-20T20:04:22.435Z (6 days ago)
- Topics: api, bot, bot-api, bot-framework, business-api, chatbot, cloud, cloud-api, deno, javascript, nodejs, npm-package, whatsapp, whatsapp-api, whatsapp-bot, whatsapp-business, whatsapp-business-api, whatsapp-cloud, whatsapp-cloud-api
- Language: TypeScript
- Homepage:
- Size: 6.87 MB
- Stars: 139
- Watchers: 8
- Forks: 32
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# whatsapp-api-js v4
[](https://www.npmjs.com/package/whatsapp-api-js)
[](#contributors)
A TypeScript server agnostic Whatsapp's Official API framework.
## List of contents
- [whatsapp-api-js v4](#whatsapp-api-js-v4)
- [List of contents](#list-of-contents)
- [Set up](#set-up)
- [Examples and Tutorials](#examples-and-tutorials)
- [Types](#types)
- [Changelog](#changelog)
- [Documentation](#documentation)
- [Contributors](#contributors)
- [Contributions](#contributions)
- [Breaking changes](#breaking-changes)
- [Beta releases](#beta-releases)
## Set up
Before all, you will need a Meta Bussiness App with WhatsApp API activated. You
can create your first app following
[this steps](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started).
- Get the API token, either a temporal or a
[permanent one](https://developers.facebook.com/docs/whatsapp/business-management-api/get-started).
- Get your App secret from the dashboard in App Settings > Basic > App Secret.
- More in-depth information on how to set and retrieve this values is available
at
[the module documentation](https://whatsappapijs.web.app/types/types.TheBasicConstructorArguments.html)
You can now install the module using npm:
```sh
npm install whatsapp-api-js
```
Which will let you write code like this:
```js
import { WhatsAppAPI } from "whatsapp-api-js";
import { Document, Image, Text } from "whatsapp-api-js/messages";
// Kind reminder to not hardcode your token and secret
const TOKEN = "YOUR_TOKEN";
const APP_SECRET = "YOUR_SECRET";
/** @type WhatsAppAPI */
const Whatsapp = new WhatsAppAPI({ token: TOKEN, appSecret: APP_SECRET });
// Assuming post is called on a POST request to your server
async function post(e) {
// Too long? Read https://whatsappapijs.web.app/modules/middleware.html
return await Whatsapp.post(
JSON.parse(e.data),
e.data,
e.headers["x-hub-signature-256"]
);
}
Whatsapp.on.message = async ({ phoneID, from, message, name, reply }) => {
console.log(
`User ${name} (${from}) sent to bot ${phoneID} ${JSON.stringify(
message
)}`
);
let response;
if (message.type === "text") {
response = await reply(
new Text(`*${name}* said:\n\n${message.text.body}`),
true
);
}
if (message.type === "image") {
response = await reply(
new Image(message.image.id, true, `Nice photo, ${name}`)
);
}
if (message.type === "document") {
response = await reply(
new Document(message.document.id, true, undefined, "Our document")
);
}
console.log(
response ??
"There are more types of messages, such as contacts, " +
"locations, templates, interactive, reactions and " +
"all the other media types."
);
Whatsapp.markAsRead(phoneID, message.id);
return 200;
};
Whatsapp.on.sent = ({ phoneID, to, message }) => {
console.log(`Bot ${phoneID} sent to user ${to} ${message}`);
};
```
To receive the messages updates, you must set-up the webhook at your Meta app.
Back in the dashboard, click on WhatsApp > Settings, write down your webhook
URL, and make sure to subscribe to the messages event. You will also be asked
for a Verify Token. This can be any string you want.
The package also includes a GET handler for the webhook authentication:
```js
import { WhatsAppAPI } from "whatsapp-api-js";
const TOKEN = "YOUR_TOKEN";
const APP_SECRET = "YOUR_SECRET";
const VERIFY_TOKEN = "YOUR_VERIFY_TOKEN";
const Whatsapp = new WhatsAppAPI({
token: TOKEN,
appSecret: APP_SECRET,
webhookVerifyToken: VERIFY_TOKEN
});
// Assuming get is called on a GET request to your server
function get(e) {
// Too long!? Read https://whatsappapijs.web.app/modules/middleware.html
return Whatsapp.get(e.query);
}
```
And that's it! Now you have a functioning Whatsapp Bot connected to your server.
For more information on the setup process for specific runtimes and frameworks,
check out the
[Environments.md file](https://github.com/Secreto31126/whatsapp-api-js/blob/main/ENVIRONMENTS.md).
## Examples and Tutorials
There are a few examples that cover how to create each type of message, and how
to use the basic methods of the library.
Check them out in the
[examples folder](https://github.com/Secreto31126/whatsapp-api-js/blob/main/EXAMPLES/).
## Types
The library is fully typed. Most types are available by importing `/types` or
`/emitters` files:
```ts
import { GetParams, PostData } from "whatsapp-api-js/types";
import { OnMessage, OnSent, OnStatus } from "whatsapp-api-js/emitters";
```
## Changelog
To know what changed between updates, check out the
[releases on Github](https://github.com/Secreto31126/whatsapp-api-js/releases).
## Documentation
The latest release documentation is available at
[whatsappapijs.web.app](https://whatsappapijs.web.app/), and previous versions
are archived at
[secreto31126.github.io/whatsapp-api-js](https://secreto31126.github.io/whatsapp-api-js/).
## Contributors
[Emoji key ✨](https://allcontributors.org/docs/en/emoji-key)
Diego Carrillo
💵
Omar
🐛 💵
Rahul Lanjewar
💻 📖 🤔
Felix Arjuna
🐛 🛡️
## Contributions
If you have some free time and really want to improve the library or fix dumb
bugs, feel free to read
[CONTRIBUTING.md file](https://github.com/Secreto31126/whatsapp-api-js/blob/main/CONTRIBUTING.md).
## Breaking changes
You can get a full list of breaking changes in the
[BREAKING.md file](https://github.com/Secreto31126/whatsapp-api-js/blob/main/BREAKING.md).
## Beta releases
Install the latest beta release with `npm install whatsapp-api-js@beta`. As any
beta, it is 110% likely to break. I also use this tag to test npm releases. Use
it at your own risk.