Sending Pools (multiple numbers)

A Sending Pool is like several checkout lines: instead of pushing everything through one number, the system splits messages across the numbers in the group, automatically.

In brief

Groups several active numbers and picks which one sends each message.
Optional, without a pool, keep using instanceId as you do today.
Each pool is official or unofficial; you cannot mix both.
Useful for large campaigns and when you want protection if one number fails.

Connection modes: Connection modes.

When to use

Situation	Use a pool?
Large campaigns (thousands of messages)	Yes
Want protection if a number fails	Yes
Low volume on a single number	Not needed
Need the same sender every time	Use `instanceId` (pool ignored)

With no pool configured, the current instanceId flow stays the same.

One type per pool

This is the main rule:

Pool type	Allowed instances
Official	Official connection only
Unofficial	Unofficial connection only

The pool type is set by the first number you add (or at creation in the dashboard). Every new instance in that pool must be the same type.

Need both modes? Create two pools (one official, one unofficial).
Try to mix when adding → SENDING_POOL_KIND_MISMATCH
Send through an inconsistent pool → SENDING_POOL_KIND_MIXED

Full codes: Error responses.

Templates, send rules, and risk differ between official and unofficial. That is why a pool never crosses modes.

How it works in practice

Create the pool in the dashboard and add active numbers of the same type
Choose how to distribute (round robin, weight, or least used today)
Send without instanceId, the default pool or sendingPoolId picks the number per recipient
If one number fails too often, the circuit breaker pauses only that one; the others keep going

With an explicit instanceId, the message goes from that number and the pool does not apply to that send.

Distribution modes

Mode	How it works	Good for
Round robin	Number 1 sends N messages, then number 2, and so on	Similar capacity across lines
Weighted	Weight 3 sends ~3× more than weight 1	One stronger or more mature number
Least used	Always the line that sent the least today	Numbers that start at different times

Main settings

Setting	What it does	Default
Switch every N messages	Batch per number before switching	50
Cooldown	Pause between batches	None
Health monitoring	Pause a number with many failures	On
Failure threshold	Error % to pause in the pool	30%
Default pool	Used when you omit `instanceId`	Per dashboard

Per number: weight, daily limit, own cooldown, and manual pause. If more than 30% of a number’s messages fail within 10 minutes, it is paused only in that pool (does not disconnect WhatsApp). When it stabilizes, it resumes on its own.

Via API

Default pool (no number chosen)

POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "to": ["5511999999999", "5511888888888"],
  "type": "text",
  "payload": {
    "message": "Your order is confirmed!"
  }
}

Specific pool

{
  "to": ["5511999999999"],
  "type": "text",
  "sendingPoolId": "POOL_ID",
  "payload": {
    "message": "Weekly promo!"
  }
}

Fixed number (ignores pool)

{
  "instanceId": "INSTANCE_ID",
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Message from this number."
  }
}

Do not send instanceId and sendingPoolId together, the API returns 400.

Best practices

Warm up new numbers before heavy campaigns: 200–500 messages/day per line at first. Daily limits in the dashboard help.

Enable cooldown on large sends (e.g. 30 s every 50 messages)
Watch the dashboard if a number was paused by the circuit breaker
See Anti-ban policy

Next steps

Introduction: channel overview
Quick Start: connect and send
Connection modes: official × unofficial
Anti-ban policy: pace and warm-up

​In brief

​When to use

​One type per pool

​How it works in practice

​Distribution modes

​Main settings

​Via API

​Default pool (no number chosen)

​Specific pool

​Fixed number (ignores pool)

​Best practices

​Next steps

In brief

When to use

One type per pool

How it works in practice

Distribution modes

Main settings

Via API

Default pool (no number chosen)

Specific pool

Fixed number (ignores pool)

Best practices

Next steps