Skip to content

WhatsApp Cloud | @chatally/whatsapp-cloud

WhatsApp Cloud is a ChatAlly server that integrates the WhatsApp Cloud API endpoints Webhooks, Messages and Media into one server module, that can be used in a ChatAlly application.

Usage

Install the required packages

Terminal window
npm install @chatally/whatsapp-cloud

Create a main module, that sets up the WhatsApp cloud server and integrates it with your ChatAlly application.

import { Application } from '@chatally/core'
import { WhatsAppCloud } from '@chatally/whatsapp-cloud'
const phoneNumberId = 'YOUR PHONE NUMBER'
const accessToken = 'YOUR ACCESS TOKEN'
const verifyToken = 'YOUR WEBHOOKS VERIFY TOKEN'
const secret = 'YOUR WEBHOOKS VALIDATION SECRET'
const whatsapp = new WhatsAppCloud({
env: false, // do not read configuration from environment variables
file: false, // do not read configuration from default configuration files
graphApi: { phoneNumberId, accessToken },
webhooks: { verifyToken, secret },
})
new Application() //
.use(whatsapp)
.use(({ req, res }) => {
if (res.isWritable) {
res.write(`You said '${req.content}' and I don't know what it means.`)
}
})
.listen()

In this example, we fully configure the WhatsApp Cloud server with a Javascript object. You could also provide options as environment variable and from a file.

The WhatsApp Cloud server starts a webserver in the background, that provides the webhooks callback endpoint to the WhatsApp cloud.

Once you have this deployed to a publicly accessible web server, you can register your WhatsApp business account to receive notifications for incoming messages or status updates. Registration is only required once.

Configuration

To set up a WhatsApp Cloud server, you must provide some configuration, either explicitly as a Javascript object, a configuration file, environment variables or a combination of it. A minimal configuration must contain:

  • graphApi.phoneNumberId The id of the registered WhatsApp number (this is not the phone number itself).
  • graphApi.accessToken A cryptographic token used as Authorization: Bearer in each call to an endpoint. See the Facebook documentation on how to create access tokens.
  • webhooks.verifyToken A shared secret used to register the webhooks endpoint with your WhatsApp business account.
  • webhooks.secret A cryptographic token to verify the payload of received event notifications on the webhooks endpoint.

There are some more options. This is an example configuration file (whatsapp-cloud.config.yaml) with all configuration options and there default values:

# name: WhatsAppCloud
# immediate: false
webhooks:
# [Optional] Port to listen on [`default=3000`]
# port: 3000
# Look these up in your WhatsApp Business settings
# Token to verify webhooks registration
verifyToken: <YOUR VERIFY TOKEN>
# Secret to verify payload signatures
secret: <YOUR SECRET>
graphApi:
# [Optional] Base URL for Meta GraphAPI
# baseUrl: "graph.facebook.com"
# [Optional] Port at which to reach Meta GraphAPI
# basePort: undefined
# [Optional] Version of the Meta GraphAPI
# version: 20
# Look these up in your WhatsApp Business settings
# the phone number id of the WhatsApp business account
phoneNumberId: <YOUR PHONE NUMBER>
# Access token to use as authorization bearer.
accessToken: <YOUR ACCESS TOKEN>
media:
# [Optional] Path to a directory where to store downloaded media assets
# [default="media"]
downloadDir: ./wa-media
# [Optional] Path to the database to store media ids
# [default="media.db"]
dbPath: ./wa-media/media-ids.db

Reference

In your application, you can use some functionality of the integrated endpoints through the server’s interface.

async send(to: string, ...outgoing: ChatMessage[]): Promise<void>

Send message(s) to recipient.

Messages are sent “in order” once the Webhooks server has been started with a call to listen(), i.e. the next message to the same recipient is only sent out, once a delivered status has been received.

  • to recipient’s phone number, with country code but without +.
  • ...outgoing one or more messages to send.

async upload(file: string): Promise<string>

Upload a file to Facebook’s media endpoint.

  • file Path to the file to be uploaded.
  • @returns the media id that can be referenced in messages

async download(id): Promise<string>

  • id Media id of the asset to be downloaded to downloadDir.
  • @returns the file path to the downloaded file

Running standalone

If you do not use the WhatsApp Cloud server in a ChatAlly application, you have to register a dispatch method explicitly and call listen() to start the server.

set dispatch(dispatch: Dispatch)

Set the dispatch method to generate a response.

You must set this beforte calling listen().

  • dispatch Method that generates responses.

Dispatch must be a function (sync or async) that takes a Request and a Response and returns void.

listen(port?: number): void

Start the underlying Webhooks API server.

This call is long-running and will only return, once the server has stopped. You must set dispatch before starting to listen, otherwise notifications would have no effect.

  • port [Optional] Port to listen on with the Webhooks server.

See https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks.

See also the WhatsApp Business Documentation

Cloud API

Webhooks

Messages

Media