One session is one number
Linking is the same mechanism as WhatsApp Web: your number stays on the phone and WaveSenda holds a linked-device socket. Everything else in the API hangs off a session.
Endpoints
Settings worth knowing
| Field | Default | Notes |
|---|---|---|
name | — | A slug you choose. Usable in place of the id in every path, which keeps configuration readable. |
auto_reconnect | true | Reopens the socket after a drop. Leave it on unless you are managing reconnection yourself. |
mark_read_on_receive | false | Sends blue ticks for everything that arrives. Off by default — reading a message you have not answered sets an expectation. |
reject_calls | false | Declines incoming WhatsApp calls automatically. A ringing unattended number is worse than a declined one. |
proxy_url | — | Routes this number through a specific egress. Useful when a number should appear to connect from its own country. |
is_sandbox | false | A mock session that acks and emits webhooks without touching WhatsApp. |
Staying connected
Sockets drop. Networks move, phones lose battery, WhatsApp restarts things. Two events are worth handling and they mean different things: session.disconnected is usually transient and recovers on its own, whereas session.logged_out means the link was removed from the handset and nothing but a fresh scan will fix it.
{
"event": "session.logged_out",
"data": {
"session": { "id": "8f14e45f-...", "name": "support" },
"reason": "unlinked_from_device"
}
}Health and ban risk
Every session carries a rolling score out of 100, recomputed on a schedule from the last 24 hours of behaviour. Below 60 the engine halves your sending rate; below 30 it stops sending entirely rather than let a number finish the job of getting itself banned.
{
"score": 72,
"risk_level": "watch",
"messages_sent": 480,
"messages_delivered": 465,
"messages_failed": 15,
"messages_received": 96,
"new_contacts_messaged": 210,
"blocks_detected": 3,
"opt_outs": 2,
"disconnect_count_7d": 1,
"uptime_percent_7d": 99.2,
"reasons": [
"High proportion of first-contact messages in the last 24 hours.",
"3 recipients appear to have blocked this number."
]
}| Risk level | Score | What happens |
|---|---|---|
healthy | — | Nothing. Send normally. |
watch | — | Worth reading the reasons. No automatic action yet. |
elevated | below 60 | Sending rate is halved automatically, if throttling is enabled on the policy. |
critical | below 30 | Sending is paused. Calls return 423 sending_paused. |
The signal that matters most is blocks_detected. A block is a recipient telling WhatsApp directly that they did not want your message, and it is weighted accordingly. Subscribe to session.at_risk if you would rather find out before the throttle bites.
Warming a new number
A brand-new number sending a thousand messages on day one is the single most reliable way to get banned. A warm-up plan replaces the policy’s daily cap with a much lower one that grows — 20 a day climbing to 1,000 over three weeks, by default.
The ramp is geometric rather than linear, because the risky part is the beginning: a linear ramp spends most of its time at volumes that were already safe, while the first few days are where numbers actually die.