WhatsApp number rotation: how to spread the load across instances

It fits operations where a single client talks to many people: a sales team with several lines, a clinic with several units, a store answering ad leads all day. Splitting the sending lowers the volume per number and keeps the operation alive when a chip drops.

It does not fit mass sends to people who never talked to you. Splitting a cold list across five numbers only spreads the problem over five chips, and consent is still what weighs most. If a number is new, warm it up first: see chip warm-up.

First, rotate only among connected numbers: read the instance list and filter by status. Second, a daily cap per number, set by you from each chip's phase (the operations sheet keeps that). Third, the same contact always uses the same number: someone who already talked to number A should not get the next message from number B, because the switch confuses the customer and looks suspicious to WhatsApp. Fourth, pause immediately any number that returns 429 or drops in status.

The third rule needs a simple table in your system: contact, source instance. Rotation applies only to new contacts. Contacts that already have an owner stay with it.

The example reads GET /instances, filters the connected ones (the status comes as CONNECTED in the reference's sample response), spins a cursor and skips any number that hit its cap. The counter lives in memory for the example only: in production keep it per day in a database, or the rotation resets on every restart. The send call is POST /{instanceId}/send/text with number and text. See the reference for the other fields.

// Round-robin sender: picks the next CONNECTED instance that is under its daily cap
const BASE = "https://api.zapzapapi.com/api/v1";
const H = {
  "Content-Type": "application/json",
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};
const DAILY_CAP = 40;          // your own limit per number, from your operations sheet
const sentToday = new Map();   // instance id -> count (persist it in a database in production)
let cursor = 0;

async function connectedInstances() {
  const res = await fetch(BASE + "/instances", { headers: H });
  if (!res.ok) throw new Error("GET /instances failed: HTTP " + res.status);
  const list = await res.json();
  return list.filter((i) => i.status === "CONNECTED");
}

function pickInstance(pool) {
  for (let n = 0; n < pool.length; n++) {
    const inst = pool[(cursor + n) % pool.length];
    if ((sentToday.get(inst.id) || 0) < DAILY_CAP) {
      cursor = (cursor + n + 1) % pool.length;
      return inst;
    }
  }
  return null; // every number hit its cap: stop and try again tomorrow
}

export async function sendBalanced(number, text) {
  const pool = await connectedInstances();
  const inst = pickInstance(pool);
  if (!inst) throw new Error("no instance available under the daily cap");
  const res = await fetch(BASE + "/" + inst.id + "/send/text", {
    method: "POST",
    headers: H,
    body: JSON.stringify({ number, text }),
  });
  if (res.status === 429) throw new Error("rate limited, back off on " + inst.name);
  if (!res.ok) throw new Error("send failed on " + inst.name + ": HTTP " + res.status);
  sentToday.set(inst.id, (sentToday.get(inst.id) || 0) + 1);
  return { instance: inst.name, status: res.status };
}

The reference lists 429 as rate limit exceeded. Treat it as a signal to back off on that number and carry on with the others, instead of retrying in a loop. If all of them hit the cap, the right answer is to stop and resume tomorrow, not to raise the cap.

Do not distribute identical bursts: vary the text, space the sends and prefer conversations to blasts. The API has per-message delay options, and the list send in /sender/simple accepts minimum and maximum delays; use them instead of sleeping in your own code for scheduled campaigns.

More numbers do not change the unit price: R$15 per active number per month, prepaid, with no per-message fee, so splitting the load across 4 numbers costs R$60 a month whatever the volume. Before creating more instances, check the cost at GET /instances/cost, which shows the activation fee and the balance needed.

Log, per number and per day: sent, replies and failures. A number whose reply rate falls while failures climb steps back a phase. For pricing at scale, see cost per number and volume and the pricing page. For who works this way, see AI agencies and traffic managers.