WhatsApp Business API – A Bird’s Eye View

This is the very first post on our new engineering blog, and I’m very excited for what we’re going to write about here. On this blog, we will provide meaningful, concise and technical information directly from our developer team.

In this article you’ll learn everything about the WhatsApp Business API in general and how it’s made – essentially, you’ll get a technical definition and understanding of how the WhatsApp Business API works.

So let’s get to it!

What is the WhatsApp Business API anyway?

The WhatsApp Business API is an interface which enables corporations to chat with their customers and send them automated messages or notifications. There are some interesting details about the way this API is implemented, especially security-wise.

WhatsApp has always had a strange position when it comes to security – despite its success right from the start, the app was infamously insecure originally. That changed with other messenger applications appearing on the stage, leading to the eventual adoption of end-to-end encryption using the Signal protocol. Signal is still regarded as the most secure messaging protocol implementation to date by the cryptography community, with no currently known security flaws.

So, with WhatsApp announcing a public API for business usage, that raised some eyebrows: How could the promise of end-to-end encryption be kept up while simultaneously hosting an API that had access to the clear-text messages?

Offer innovative customer care with the Messenger Communication Platform today.
Access all features in a 14-day free trial.

In fact, it can. Engineers at Facebook executed some clever tricks to actually ensure that messages stay secure, all the way from a client’s device to the Business API user’s backend. That’s because the API runs directly on the user’s backend! To make this possible, Facebook provides a docker image that hosts both the user-facing REST API (which is a PHP application built on the Symfony framework, interestingly) and a proprietary, pre-compiled C++ backend service responsible for communicating with the actual WhatsApp servers. Additionally, the container uses an external MySQL database for its storage.
The flow of a message roughly looks like this:

Once a client sends a message to a business account, say, ACME Inc., it will be encrypted locally and sent to the WhatsApp data center. That’s the exact same flow as for ordinary messages to other WhatsApp users (If you’re looking for a good read, Moxie Marlinspike, the inventor of the Signal protocol, has explained this in great detail here). WhatsApp then resolves the recipient’s number to the current ACME Inc. “client” IP address. There’s no DNS TXT magic involved, so WhatsApp likely uses some dynamic DNS approach for both mobile and business clients. The message – still encrypted – is relayed to the ACME Docker container, where it is decrypted and stored for ACME, Inc. to fetch.
What’s important here is that the Docker container that hosts the Business API really is just a slimmed-down WhatsApp client, just like the mobile app or, by extension, WhatsApp web, just with a REST interface instead of a GUI. It also has its own set of private keys used for the message cryptography, and thus acts like a black box to both ACME, Inc. and WhatsApp itself!

Lego Bricks

Looking at the individual components, the system is modular and pretty well designed. Let’s take a technical look into the API and define the working parts:

  • A REST API container:
    The API container provides REST endpoints to interact with the Business API. It consists of a lighttpd reverse proxy in front of php-fpm, providing the Symfony REST application. The PHP side of things is pretty standard – after all, it validates input and proxies calls to the backend service via TCP sockets.
  • One or more backend service containers:
    The backend service runs the C++ CoreApp application communicating with the WhatsApp servers. This is the only component we cannot analyze, since it uses encrypted connections exclusively.
  • An external/containerized database:
    WhatsApp provides two possibilities in its documentation: Using a separate database container or connecting to an existing MySQL database server. Depending on how the network is structured, both might make sense: For instance, we’ve configured all containers to use our redundant WhatsApp database cluster.
  • Custom backend processor:
    As soon as the container receives an incoming message, it will trigger a pre-configured webhook and include all message details in the payload. This is the part business users need to implement by themselves.

Offer innovative customer care with the Messenger Communication Platform today.
Access all features in a 14-day free trial.

Due to the flexibility of using Docker, the whole thing scales pretty well: There’s even a lengthy description on how to build a high-availability setup that involves multiple CoreApp containers to distribute the workload.

To put this in perspective, after setting up the API correctly according to the WhatsApp documentation, it will act just like a third-party, remote REST API – all while hosting it yourself. To use the API in an actual product though, you’d need to incorporate it in some sort of container cluster, taking care of security, redundancy, resource management and a lot more, of course. At MessengerPeople, we’ve built a solid infrastructure around this, making it possible to use connectors for pretty much every common messenger app – being able to expose a standardized interface for WhatsApp as well as iMessage, Facebook Messenger, Viber and Telegram is great!

Using our Messenger Communication Platform, you’ll get access to our REST API which provides unified endpoints for all messaging apps. After booking a package and configuring the app, all you need to send a message via the API is the following HTTP call:

POST https://rest.messengerpeople.com/api/v7/chat 
{"id": "49123123456","message":" "Hello world!"}

After submitting the message, it will be parsed and processed, proxied to the appropriate WhatsApp Business container, encrypted, dispatched into the WhatsApp network and finally pushed to your device, which decrypts the message. After a few seconds, you’ll see that lovely Hello World notification popping up on your screen.
The API provides lots of other interesting capabilities we’ll write about in future posts. Stay tuned!

As communication becomes more and more mobile-focused, messaging apps will only grow in importance. Companies offering messaging app customer service already have a clear competitive edge over companies with slower, old-fashioned service. If you’re interested in specific tips on how to use messaging apps for customer service, messaging app usage data, or customer case studies, check out our free webinars:

Free Webinars: Chatbots & Messenger Communication

Have a great idea for customer service via messaging apps and want to talk about it? Message us!