Skip to content
Two green building blocks looking like chat bubbles ChatAlly
Docs
Blog

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