Designing sending limits for a WhatsApp messaging API
FoxlyFlow is a provider-neutral HTTP API for sending and receiving messages. The first connector talks to WhatsApp through linked-device sessions. That connector is unofficial, which means the hard problem isn't sending a message. It's sending messages in a way that doesn't get the number restricted.
Most of the interesting design work went into limits.
Limits at every level
Requests are limited before they're even authenticated, then again at each layer:
- Per client IP.
- Per API key.
- Per workspace, across all its keys.
- Per channel, for messages accepted.
Those protect the API. A second set protects the channel (the phone number), and that's where the real decisions are.
Channel sending limits
- Rate caps per minute, hour and day.
- Warm-up. A new channel starts with a small daily cap that grows by a fixed factor each day until it reaches the normal limit. New numbers that suddenly send hundreds of messages look like spam, because they usually are.
- New contacts per day. Messaging people who never wrote to you is the riskiest thing a number can do, so it gets its own small cap.
- Duplicate text per hour. The same message sent over and over is another spam signal.
- A random gap between sends, so traffic doesn't look machine-timed.
- Quiet hours in the channel's own time zone. No outreach at night to people who haven't written in the last 24 hours. Daily caps reset at the channel's midnight, not the server's.
- Back off when restricted. When WhatsApp signals the number is restricted, the channel stops messaging new contacts.
Held, not dropped
When a message doesn't fit the limits, it stays queued and goes out when it fits. Nothing is silently dropped. From the client's side, a send is a promise: you'll either get the message delivered or a clear failure through a webhook, never silence.
That pairs with two other guarantees:
- Idempotency keys. Retrying a request with the same key returns the original message instead of sending twice.
- Signed webhooks with retries, so your endpoint can verify each event came from FoxlyFlow and won't miss one because it was briefly down.
Small to run
It's a modular monolith: one Go binary that runs as an api process and a worker process. Postgres is the source of truth; Redis holds only transient things like queues, rate-limit counters, locks and QR codes. The standalone container runs the API, the worker and Redis together in a 64 MB image using about 50 MB of RAM when idle.
The takeaway
When you build on a platform you don't control, the limits are the product. Rate limits protect your servers. Sending limits protect your users' numbers, and that's what they're actually paying for.