whatsapp
Connector
¶ User-initiated WhatsApp mutations
Foreground traffic that a user is waiting on. This queue must stay free of slow background work.
connect
send
media send
location
reaction
mark read
history resync
group operations
Queue ownership
¶ Queue System
Every queue has one consumer and one job class. The connector owns the WhatsApp-facing queues, API workers own orchestration, and slow background work never shares a lane with user-initiated sends.
Connector consumes 3 queues
API workers orchestrate
Slow work off
whatsapp
whatsapp_media
Connector
¶ Slow media download work
Background media downloads run here so they cannot occupy slots needed for sends.
whatsapp_avatars
Connector
¶ Slow avatar fetch work
Background avatar fetches run here, isolated from foreground traffic.
scheduled
flow_runs
broadcasts
API workers
¶ Orchestration
These workers decide when to send, then call the same producer functions as synchronous endpoints. They never talk to WhatsApp directly.
Keep slow background work off the
whatsapp queue
Media downloads and avatar fetches belong on their own queues.
Orchestration workers never talk to WhatsApp directly
They go through the producer functions, which enqueue onto the connector queues.
History imports
¶ History-import pairing queue
First-time WhatsApp links that require history import may be queued before a QR is requested, so only a bounded number of heavy imports run concurrently. The queue and its admission limits prevent connector memory and CPU freezes; abandoned pairing screens must not permanently hold slots.
The API exposes POST /organizations/{org}/channels/{id}/pairing-lease, which returns a PairingQueueState: queued flag, pairing_queued_at, position, queue_length, importing, limit, and admitting (server memory alarm).
Open pairing screens renew their lease periodically: the client renews every 20s and the server lease allows about 90s. Each renewal patches the channels cache, so promotions are picked up even if realtime events were missed.
If the user closes the pairing screen while queued, the client sends DELETE pairing-queue so the next queued channel can begin importing immediately.
Bounding concurrent history imports keeps heavy first-link imports from exhausting connector memory and CPU, the same reason slow work stays off the whatsapp queue.
Production safety
¶ Queue segregation is a safety rule
Treat queue ownership and placement as a safety rule. Rebalancing or consolidating queues can reintroduce incidents where background jobs block foreground traffic.
Keep job kinds split across queuesBackground work cannot occupy slots needed for user-initiated sends.
Misplaced work causes user-visible send delaysA slow job on the wrong queue delays the sends users are waiting on.
Do not rebalance or consolidate queuesDoing so can reintroduce incidents where background jobs block foreground traffic.