whatsapp-api-js

whatsapp-api-js v4

A TypeScript server agnostic Whatsapp's Official API framework.

List of contents

• whatsapp-api-js v4
  • List of contents
  • Set up
  • Examples and Tutorials
  • Types
  • Changelog
  • Documentation
  • Contributors
  • Contributions
  • Breaking changes
  • 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.

• Get the API token, either a temporal or a permanent one.
• 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

You can now install the module using npm:

npm install whatsapp-api-js

Which will let you write code like this:

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<number> */
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:

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.

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.

Types

The library is fully typed. Most types are available by importing /types or /emitters files:

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.

Documentation

The latest release documentation is available at whatsappapijs.web.app, and previous versions are archived at secreto31126.github.io/whatsapp-api-js.

Contributors

Emoji key ✨

Diego Carrillo 💵

Omar 🐛 💵

Rahul Lanjewar 💻 📖 🤔

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.

Breaking changes

You can get a full list of breaking changes in the BREAKING.md file.

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.