Main entry point for the API.
It's highly recommended reading the named parameters docs at
types.TheBasicConstructorArguments,
at least for token, appSecret and webhookVerifyToken properties,
which are the most common in normal usage.
The other parameters are used for fine tunning the framework,
such as ponyfill, which allows the code to execute on platforms
that are missing standard APIs such as fetch and crypto.
If fetch is not defined in the enviroment and the provided ponyfill isn't a function
If secure is true, crypto.subtle is not defined in the enviroment and the provided ponyfill isn't an object
The callbacks for the events (message, sent, status)
const Whatsapp = new WhatsAppAPI({
token: "my-token",
appSecret: "my-app-secret"
});
// Set the callback
Whatsapp.on.message = ({ from, phoneID }) => console.log(`Message from ${from} to bot ${phoneID}`);
// Remove the callback
Whatsapp.on.message = undefined;
Send the same Whatsapp message to multiple phone numbers.
In order to avoid reaching the
API rate limit,
this method will send the messages in batches of 50 per second by default,
but this can be changed using the batch_size and delay parameters.
The API rate limit can be increased by contacting Facebook as explained here.
The bot's phone ID
The users' phone numbers
A Whatsapp message, built using the corresponding module for each type of message.
The number of messages to send per batch
The delay between each batch of messages in milliseconds
The server response
import WhatsAppAPI from "whatsapp-api-js";
import Text from "whatsapp-api-js/messages/text";
const Whatsapp = new WhatsAppAPI({
token: "YOUR_TOKEN",
appSecret: "YOUR_APP_SECRET"
});
const phoneID = "YOUR_BOT_NUMBER";
const users = ["YOUR_USER1_NUMBER", "YOUR_USER2_NUMBER"];
const message = new Text("Hello World");
const responses = Whatsapp.broadcastMessage(phoneID, users, message);
Promise.all(responses).then(console.log);
if batch_size is lower than 1
if delay is lower than 0
Generate a QR code for sharing the bot
The bot's phone ID
The quick message on the QR code
The format of the QR code
The server response
Delete a Media object with an ID
The Media's ID
Optional phoneID: stringBusiness phone number ID. If included, the operation will only be processed if the ID matches the ID of the business phone number that the media was uploaded on.
The server response
Delete a QR code of the bot
The bot's phone ID
The QR's id to delete
The server response
Get a Media fetch from an url. When using this method, be sure to pass a trusted url, since the request will be authenticated with the token.
The Media's url
The fetch raw response
If url is not a valid url
import WhatsAppAPI from "whatsapp-api-js";
const token = "token";
const appSecret = "appSecret";
const Whatsapp = new WhatsAppAPI({ token, appSecret });
const id = "mediaID";
const { url } = await Whatsapp.retrieveMedia(id);
const response = Whatsapp.fetchMedia(url);
GET helper, must be called inside the get function of your code. Used once at the first webhook setup.
The request object sent by Whatsapp
The challenge string, it must be the http response body
500 if webhookVerifyToken is not specified
400 if the request is missing data
403 if the verification tokens don't match
GET request handler for node:http server
The request object
The challenge string to be sent to the client
import { createServer, IncomingMessage, ServerResponse } from 'node:http';
import WhatsAppAPI from "whatsapp-api-js/middleware/node-http";
const server = createServer((request: IncomingMessage, response: ServerResponse) => {
if (request.url === "/message" && request.method === "GET") {
try {
response.statusCode = 200;
response.end(Whatsapp.handle_get(request));
} catch (e) {
response.statusCode = e as number;
response.end();
}
}
});
server.listen(5000);
The error code
POST request handler for node:http server
The request object
The status code to be sent to the client
import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
import WhatsAppAPI from "whatsapp-api-js/middleware/node-http";
const Whatsapp = new WhatsAppAPI({
token: "YOUR_TOKEN",
appSecret: "YOUR_APP_SECRET",
webhookVerifyToken: "YOUR_WEBHOOK_VERIFY_TOKEN"
});
const server = createServer(async (request: IncomingMessage, response: ServerResponse) => {
if (request.url === "/message" && request.method === "POST") {
response.statusCode = await Whatsapp.handle_post(request);
response.end();
}
});
server.listen(5000);
Mark a message as read
The bot's phone ID
The message ID
The server response
POST helper, must be called inside the post function of your code. When setting up the webhook, only subscribe to messages. Other subscritions support might be added later.
The POSTed data object sent by Whatsapp
Optional raw_body: stringThe raw body of the POST request
Optional signature: stringThe x-hub-signature-256 (all lowercase) header signature sent by Whatsapp
200, it's the expected http/s response code
// author arivanbastos on issue #114
// Simple http example implementation with Whatsapp.post() on Node@^19
import WhatsAppAPI from "whatsapp-api-js";
import { NodeNext } from "whatsapp-api-js/setup/node";
import { createServer } from "http";
const token = "token";
const appSecret = "appSecret";
const Whatsapp = new WhatsAppAPI(NodeNext({ token, appSecret }));
function handler(req, res) {
if (req.method == "POST") {
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", async () => {
const body = Buffer.concat(chunks).toString();
try {
const response = await Whatsapp.post(JSON.parse(body), body, req.headers["x-hub-signature-256"]);
res.writeHead(response);
} catch (err) {
res.writeHead(err);
}
res.end();
});
} else res.writeHead(501).end();
};
Whatsapp.on.message = ({ phoneID, from, message, name }) => {
console.log(`User ${name} (${from}) sent to bot ${phoneID} a(n) ${message.type}`);
};
const server = createServer(handler);
server.listen(3000);
500 if secure and the appSecret isn't specified
501 if secure and crypto.subtle or ponyfill isn't available
400 if secure and the raw body is missing
401 if secure and the signature is missing
401 if secure and the signature doesn't match the hash
400 if the POSTed data is not a valid Whatsapp API request
Get a Media object data with an ID
The Media's ID
Optional phoneID: stringBusiness phone number ID. If included, the operation will only be processed if the ID matches the ID of the business phone number that the media was uploaded on.
The server response
Get one or many QR codes of the bot
The bot's phone ID
Optional id: stringThe QR's id to find. If not specified, all QRs will be returned
The server response
Send a Whatsapp message
The bot's phone ID
The user's phone number
A Whatsapp message, built using the corresponding module for each type of message.
Optional context: stringThe message ID of the message to reply to
The server response
import WhatsAppAPI from "whatsapp-api-js";
import Text from "whatsapp-api-js/messages/text";
const Whatsapp = new WhatsAppAPI({
token: "YOUR_TOKEN",
appSecret: "YOUR_APP_SECRET"
});
Whatsapp.sendMessage(
"BOT_PHONE_ID",
"USER_PHONE",
new Text("Hello World")
).then(console.log);
Update a QR code of the bot
The bot's phone ID
The QR's id to edit
The new quick message for the QR code
The server response
Upload a Media to the server
The bot's phone ID
The Media's FormData. Must have a 'file' property with the file to upload as a blob and a valid mime-type in the 'type' field of the blob. Example for Node ^18: new FormData().set("file", new Blob([stringOrFileBuffer], "image/png")); Previous versions of Node will need an external FormData, such as undici's. To use non spec complaints versions of FormData (eg: form-data) or Blob set the 'check' parameter to false.
If the FormData should be checked before uploading. The FormData must have the method .get("name") to work with the checks. If it doesn't (for example, using the module "form-data"), set this to false.
The server response
If check is set to true and form is not a FormData
If check is set to true and the form doesn't have valid required properties (file, type)
If check is set to true and the form file is too big for the file type
import WhatsAppAPI from "whatsapp-api-js";
const token = "token";
const appSecret = "appSecret";
const Whatsapp = new WhatsAppAPI({ token, appSecret });
// If required:
// import FormData from "undici";
// import { Blob } from "node:buffer";
const form = new FormData();
// If you don't mind reading the whole file into memory:
form.set("file", new Blob([fs.readFileSync("image.png")], "image/png"));
// If you do, you will need to use streams. The module "form-data",
// although not spec compliant (hence needing to set check to false),
// has an easy way to do this:
// form.append("file", fs.createReadStream("image.png"), { contentType: "image/png" });
console.log(await Whatsapp.uploadMedia("phoneID", form));
// Expected output: { id: "mediaID" }
Generated using TypeDoc
node:http server middleware for WhatsAppAPI