WhatsApp Business API and omnichannel customer support

After voice and SMS, the third channel we built into our customer support systems is WhatsApp. This post is about how the WhatsApp Business Platform Cloud API works from a developer’s point of view, where the pitfalls are, and how we fitted it into a system where the customer sees calls, SMS messages and WhatsApp messages on a single screen.

Cloud API: what you get and what you do not

The Cloud API is an HTTP interface: you send a message with a POST request, and you receive incoming messages and status changes over a webhook. There is no client that needs its own server, and no phone running WhatsApp. That is a big step forward compared to the earlier on-premise solutions.

What you have to accept in return:

• the phone number is tied to a WhatsApp Business account, and verifying the account (business details, display name) can take days,
• the platform rules are strict: unsolicited messages are not allowed, and user reports degrade the number’s quality rating, which results in sending limits,
• the API is versioned and changes regularly, so we pin the version explicitly and schedule upgrades deliberately.

Templates and the 24-hour window

WhatsApp distinguishes between two message types, and this is the single most important concept of the whole integration.

Session message. If the user writes to us, we can reply with any free-form text within 24 hours. The window restarts with every incoming message.

Template message. Outside the window, or when we initiate, only a pre-approved template can be sent. The template text can contain variables (name, appointment, order number), but its structure is approved by the platform, by category (transactional, marketing, authentication).

In practice this means the system has to track when the last incoming message was in each conversation, and decide before sending whether free text is allowed or a template is required. We solve this in the sending layer: the application “sends a message”, and the layer decides whether it is inside the window, and if not, maps it to the appropriate template or rejects the send with a meaningful error.

Template approval is a workflow of its own. Rejections are not always explained in detail, so it is worth keeping templates simple and unambiguous, and putting marketing-style copy into its own category.

Webhooks and reliability

Incoming messages, delivery and read statuses all arrive on the same webhook endpoint. A few rules we follow here:

• we verify the webhook signature (HMAC) on every request and drop unauthenticated ones,
• the endpoint responds with 200 immediately and queues the processing; if processing is slow, the platform retries and duplicates appear,
• processing is idempotent on the message ID, because retries happen regardless,
• the order of status updates (sent, delivered, read) is not guaranteed, so we only ever move the status “forward”.

The webhook endpoint is the most critical entry point in the system: if it goes down, customer messages are lost or delayed. That is why we monitor it separately and log the raw incoming events before processing them.

One inbox, three channels

From a support perspective, WhatsApp is not a separate system but another channel to the same customer. The goal is a unified inbox where a call, an SMS and a WhatsApp message appear one after another on a single customer timeline.

For this we use a channel-agnostic event model: every interaction belongs to a conversation, tied together by the customer’s identifier (typically the phone number). The event type (inbound call, outbound SMS, WhatsApp message) is just an attribute. The agent interface therefore shows a single list, and the system suggests the reply channel: if the customer wrote on WhatsApp and the window is open, we reply there; if it has expired, it offers an SMS or a template.

This architecture is also what makes chatbot flows possible. Automated replies (opening hours, appointment booking, status lookup) run as a simple state machine over the conversation, and when the bot cannot move forward, it hands the conversation to an agent together with the full history. The bot works on the same event model as the human, so the handover loses no data.

GDPR and data handling

A WhatsApp integration processes personal data: phone number, name, message content. What we therefore clarify with the client on every rollout:

• the legal basis for processing (typically performance of a contract or consent), and how the user can opt out,
• the retention period: we do not store messages forever, and deletion is automatic and logged,
• the data processing agreement with the platform operator, and the fact that the content also passes through the platform’s servers,
• stored data stays on servers inside the EU, encrypted, with access logging.

The technical solution is simple; it is the regulatory part that takes time, and it is worth dealing with at the start of the project rather than the week before launch.

While building omnichannel support it became increasingly clear to us that the next step is not another channel but deeper automation. We will probably write more about that in the coming months.