WhatsApp gateway

An internal service our other systems use to send WhatsApp messages: a verification code for a login, a note that an order is on its way, a reminder about tomorrow's appointment. The calling application makes one API call and knows nothing about how WhatsApp works.

The service is part of our own infrastructure, so its address is not published here.

What it is used for

• One-time verification codes and login messages
• Transactional messages: order received, driver on the way, booking confirmed
• Reminders and notices where the recipient has opted in
• One sending channel for every project — each application does not build its own

How it works

An API call does not send the message directly. The message is written to a queue, and a separate sending node picks it up, delivers it and reports the outcome back. The same queue carries scheduled messages and retries.

Message state moves through a clear chain: queued → claimed → sent → delivered → read, or failed. The calling application can either poll the API or register a callback address that state changes are pushed to. Callbacks are signed with an HMAC digest the receiver can verify — nobody can feed an application a forged "delivered".

Every message must declare a category: verification, transactional, notification or marketing. The opt-out list applies to notifications and marketing; a verification code always goes through, because blocking one would lock a user out of their own account.

Duplicate sends are prevented by a caller-supplied key: the same key twice means one message, even if the network dropped mid-call.

Technology

• PHP + MySQL for the API, the queue and the admin view
• Node.js sending nodes, which can be spread across several locations
• Per-client API keys, rate limits and scopes
• Signed callbacks with retries at increasing intervals
• Admin view: nodes, messages, states and logs