whatsapp-cloud-api-express

A set of Node.js and Express.js functions for sending/receiving Whatsapp messages using the Whatsapp Cloud API.

Features:

All features in here, plus:

🔥 Added a way to listen for message status changes in messages. This allows to listen for delivered, failed, read,... statuses on the sent messages.
🔥 Added sendReaction function to react to a message.
🔥 Made the webhook able to run on serverless environments (like Google Cloud Functions).¹
✅ Added to_phone_number so you can identify which phone number was the one receiving the message.
✅ Added support for type button in incoming messages. Which is generated when the user "replies" from a template button.
✅ Added a logging callback for each message sent so you can log each sent message easily.
✅ Changed the architecture so we can use the webhook and the sender separately.
✅ Added 'parameters' type for template header component.

Install

npm install whatsapp-cloud-api-express

Usage

You can use this library only to send Whatsapp messages or only to receive Whatsapp messages or you can do both.

Beforehand you should get some values from the Facebook developers website, you can use the part (1) of this amazing tutorial by @tawn33y.

Receiving messages

The webhook part of the API is implemented as an express router. The webhook is the part that allows you to listen for new messages incoming to your bot. You can use it like this:

app.use(
  '/webhook/whatsapp', // you can change this path to whatever you want,
  // but make sure to change it on the Facebook Developer Console too
  getWebhookRouter({
    // fill your own values here:
    webhookVerifyToken: process.env.WHATSAPP_WEBHOOK_VERIFICATION_TOKEN ?? '',
    onNewMessage,
  })
);

You will need to verify the webhook with Facebook. You can either deploy this to a server or deploy locally and use ngrok, the @tawn33y tutorial above has a section about using ngrok and verifying.

This library has been tested on v15.0 and v17.0 of the webhook API.

Sending messages

First, create a sender like this:

const sender = createMessageSender(
  // fill your own values here:
  process.env.NUMBER_ID ?? '',
  process.env.ACCESS_TOKEN ?? ''
);

To send a message you can check this guide (omit createBot, startExpressServer and on as those were removed here). You can find some examples in there too.

Here is an "almost complete" example of the integration using Google Cloud Functions and Firestore to display the messages using this: https://gist.github.com/j05u3/b3ad1d5d9106a918941587e03c1919b1, let me know if you have any questions/doubts ✌️.

Some recommendations

If you are using serverless I suggest to set min instances (in Google Cloud Functions) or reserved concurrency (in AWS) to at least 1 (~4 USD or less in monthly cost) so your bot responds fast without being affected by cold starts.
Make sure to only allowlist the Facebook IPs in your serverless environment. See here for the IPs.
Make sure your onNewMessage function resolves in a 'reasonable time'. Not sure how long yet, but in a project where we were sleeping one minute Whatsapp servers started retrying the call to the webhook.

Related work

I built an open-source chats visualization frontend here that you can use to visualize your chats, it's compatible with this library ✌️.

I also built monaguillo.org using this library.

Attribution

This project was based on https://github.com/j05u3/whatsapp-cloud-api which is a fork of https://github.com/tawn33y/whatsapp-cloud-api. Thanks to @tawn33y and the community for the hard work.

This project was started using the template: https://github.com/ryansonshine/typescript-npm-package-template.

This is because on the webhook now we wait for callbacks to finish before the response is sent (sendStatus), this was done because on serverless environments code is not guaranteed to be kept alive after the response is sent. ↩

luisotee / whatsapp-cloud-api-express Goto Github PK