whatsapp-api-js

whatsapp-api-js

A Whatsapp's Official API framework for Node.js (and others)

Disclaimers

1. Whatsapp's Official API is now generally available. To get started, you can follow this steps.

2. This project is a work in progress. Breaking changes are expected from mid-version to mid-version until it hits version 1.0.0.

3. To know what changes between updates, check out the releases on Github.

Set up

First, you need a Facebook app with the Whatsapp API activated. You can create your first app following this steps. Get the API token, either a temporal or a permanent one.

In your server you can install the module using npm:

npm install whatsapp-api-js

Now you can write code like this:

const { WhatsAppAPI, Handlers, Types } = require("whatsapp-api-js");
const { Text, Media, Contacts } = Types;

const Token = "YOUR_TOKEN";

const Whatsapp = new WhatsAppAPI(Token);

// Assuming post is called on a POST request to your server
function post(e) {
    // The Handlers work with any middleware, as long as you pass the correct data
    return Handlers.post(JSON.parse(e.data), onMessage);
}

function onMessage(phoneID, phone, message, name, raw_data) {
    console.log(`User ${phone} (${name}) sent to bot ${phoneID} ${JSON.stringify(message)}`);

    let promise;

    if (message.type === "text") promise = Whatsapp.sendMessage(phoneID, phone, new Text(`*${name}* said:\n\n${message.text.body}`));

    if (message.type === "image") promise = Whatsapp.sendMessage(phoneID, phone, new Media.Image(message.image.id, true, `Nice photo, ${name}`));

    if (message.type === "document") promise = Whatsapp.sendMessage(phoneID, phone, new Media.Document(message.document.id, true, undefined, "Our document"));

    if (message.type === "contacts") promise = Whatsapp.sendMessage(phoneID, phone, new Contacts.Contacts(
        [
            new Contacts.Name(name, "First name", "Last name"),
            new Contacts.Phone(phone),
            new Contacts.Birthday("2022", "04", "25"),
        ],
        [
            new Contacts.Name("John", "First name", "Last name"),
            new Contacts.Organization("Company", "Department", "Title"),
            new Contacts.Url("https://www.google.com", "WORK"),
        ]
    ));

    if (promise) promise.then(console.log);
    
    Whatsapp.markAsRead(phoneID, message.id);
}

Whatsapp.logSentMessages((phoneID, phone, message, raw_data) => {
    console.log(`Bot ${phoneID} sent to user ${phone} ${JSON.stringify(message)}\n\n${JSON.stringify(raw_data)}`);
});

To recieve the post requests on message, you must setup the webhook at your Facebook app. While setting up, you will be asked a Verify Token. This can be any string you want.

The app also has a GET wizard for the webhook authentication:

const { Handlers } = require("whatsapp-api-js");

// Assuming get is called on a GET request to your server
function get(e) {
    // The Handlers work with any middleware, as long as you pass the correct data
    return Handlers.get(JSON.parse(e.params), "your_verify_token");
}

Once you are done, click administrate, and set the webhook to subscribe to messages only. There might be a future update to support the other types of subscriptions.

And that's it! Now you have a functioning Whatsapp Bot connected to your server.

Running outside of Node.js

Since @0.4.2, the module will check if fetch is available, and fallback to "cross-fetch" if not. This will allow the same script to be run in many different enviroments, such as a web browser, Deno and Bun.

Personal suggestion, use esm.sh to import the code directly from npm, works flawlessly with Deno. Bun seems to be more picky with the urls, but using bun install whatsapp-api-js works great for me.

Some examples:

import { WhatsAppAPI } from "https://esm.sh/whatsapp-api-js";
const Whatsapp = new WhatsAppAPI("YOUR_TOKEN_HERE");

<script type="module">
 import { WhatsAppAPI } from "https://esm.sh/whatsapp-api-js";
 const Whatsapp = new WhatsAppAPI("YOUR_TOKEN_HERE");
 <!-- Please, never use your API tokens in a website, use this method wisely -->
</script>

Breaking changes in 0.6.0

Since 0.6.0, the module will no longer return the raw fetch request, now it's internally parsed and returned. This change was made in order to improve the logSentMessages function, as it can now log the server response too. To get the raw request as before, you can use the parsed property of the main object as follows.

const parsed = false;
const Whatsapp = new WhatsAppAPI("YOUR_TOKEN", undefined, parsed);
// All the API operations, like sendMessage, will now return the raw request.
// Keep in mind, now when using logSentMessage the id and response parameters will be undefined.

Documentation

The package documentation is available in whatsappapijs.web.app and secreto31126.github.io/whatsapp-api-js.

Beta releases

Install the latest beta realease 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.

Comments

Even though the code already supports all the message types, there's still a long way to go. I will keep updating it until I like how it works.

Also, if you are interested in Google App Script support, check out Secreto31126/whatsapp-api-google-app-script.