Building a Scalable WhatsApp API for Africa

The Challenge

Building a reliable WhatsApp API for the African market means designing for unpredictable network conditions, multi-device WhatsApp protocols, and high message throughput — all while keeping the developer experience simple.

When we started Uno SAP, we had three core requirements:

• Multi-session by default — businesses shouldn't need to spin up infrastructure for every WhatsApp number
• Automatic reconnection — WhatsApp sessions drop. Recovery should be invisible to the developer
• One clean REST API — no WebSocket wrangling, no custom protocols, just HTTP

Multi-Session Architecture

Our core insight was that businesses need multiple WhatsApp numbers — sales lines, support queues, ops notifications — and managing them individually doesn't scale. Each Uno SAP session runs as an isolated connection pool with its own API key, health metrics, and webhook configuration.

Under the hood, each session maintains a persistent connection to WhatsApp's multi-device protocol. We built connection pooling, automatic QR re-generation, and pairing code support so developers never have to think about the transport layer.

// Each session gets its own isolated connection pool
const sessions = new Map<string, Session>()

// Create a new session with one POST
await api.post('/v1/sessions', {
  displayName: 'Support Line',
  webhookUrl: 'https://myapp.com/hooks'
})

// Sessions auto-connect and stay connected

Health Scoring That Actually Works

We built a 0–100 health scoring system that considers connection state, message delivery rate, reconnection attempts, and protocol-level heartbeats. A session at 94 means it's healthy and sending messages. A session at 61 means it's recovering — and you should investigate.

The health score is exposed in the dashboard and via the API, so you can build your own monitoring on top of it. We also expose individual metrics like uptime percentage, reconnection count, and time since the last event.

"The health score isn't just a number — it's a triage tool. When something breaks at 2am, you want to know exactly which session to look at."

What We Learned

After processing millions of messages, here's what stuck:

• Exponential backoff works, but you need jitter. Without randomness in reconnection timing, you get thundering-herd problems across sessions.
• Pairing codes dramatically reduce setup friction. Scanning QR codes is fine for one device, but when you're managing 20 sessions, typing a code is faster.
• Session-scoped API keys are worth the complexity. Giving each session its own key means developers can ship to production without worrying about cross-session data leaks.

We're continuing to invest in reliability, observability, and developer experience. If you're building on top of WhatsApp in Africa, we'd love to hear from you.