Varios números de WhatsApp en un solo sistema: guía de multiinstancia

Hay tres motivos recurrentes. El primero es el aislamiento de fallas: si un número se cae o es restringido, solo ese se detiene. El segundo es la separación de funciones, como atención, ventas y cobranza en números distintos, lo que además aclara la conversación para el cliente. El tercero es el modelo de agencia o software house, donde cada cliente final tiene su número y su historial.

Separar no es una forma de esquivar límites. Repartir un mismo envío en frío entre muchos números repite el patrón que genera denuncias y agrava el riesgo; lee la matriz de riesgo. La multiinstancia sirve para organizar y aislar, no para multiplicar volumen.

Cada instancia tiene un ID. Tu sistema necesita una tabla que una ese ID con el dueño del número. Un diseño mínimo:

Guarda las claves de la API (x-api-key y x-api-secret) en el servidor, en variables de entorno o una bóveda de secretos. La autenticación es de la cuenta y el ID de la instancia va en la ruta de cada llamada, así que un único par de claves opera todos los números. Detalles en autenticación.

La API de gestión tiene endpoints para listar, crear, consultar y eliminar instancias. Antes de crear, el endpoint de costo informa la tarifa de activación, el proporcional y el saldo necesario, y la creación descuenta del saldo de la cuenta. El nombre acepta solo letras, números, guion bajo y guion. Tras crearla, la instancia queda pendiente hasta que el número se empareje con un código QR.

El flujo típico en un onboarding automático: consultar costo, crear la instancia, guardar el ID, pedir el código QR, mostrarlo al cliente para que lo lea, configurar el webhook y seguir el estado hasta que pase a conectado. El fragmento siguiente hace esto en Node.js 18 o superior.

const BASE = "https://api.zapzapapi.com/api/v1";
const headers = {
  "Content-Type": "application/json",
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};

async function call(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(method + " " + path + " -> " + res.status);
  return res.json();
}

const cost = await call("GET", "/instances/cost");
console.log("total to create:", cost.total);

const created = await call("POST", "/instances", { name: "cliente-042-vendas" });
const id = created.instance.id;

await call("PUT", "/instances/" + id + "/webhook", {
  webhook_url: "https://app.example.com/hooks/whatsapp/" + id,
});

const all = await call("GET", "/instances");
console.log(all.map((i) => i.name + " " + i.status));

Configura para cada instancia una URL propia que lleve el ID, por ejemplo /hooks/whatsapp/ seguido del ID. Así, cuando llega el evento, tu servidor ya sabe de qué número vino y a qué cliente pertenece, sin adivinar por el contenido. Valida el origen con un secreto tuyo en la URL o en un encabezado, y responde 2xx rápido, dejando el procesamiento pesado para una cola.

Revisa qué está llegando con el endpoint de entregas recientes y el de errores del webhook, y prueba la URL con el endpoint de prueba. Vale leer la guía de recibir mensajes por webhook y la página de webhooks. Para herramientas de automatización, la integración con n8n muestra el diseño con una URL por flujo.

El envío usa el ID de la instancia en la ruta, así que elegir el número de salida es elegir el ID. Mantén en el sistema una regla explícita de enrutamiento: por cliente, por función o por cola. Evita sortear entre números para la misma conversación, porque el cliente debe ver siempre el mismo contacto.

En un flujo de atención, la respuesta sale de la misma instancia que recibió el mensaje. En un flujo de cobranza, sale de la instancia de la función de cobranza. Documenta esas reglas en tu código para que quien entre al equipo las entienda sin preguntar.

curl -X POST https://api.zapzapapi.com/api/v1/ID_DA_INSTANCIA/send/text \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"number":"5511999999999","text":"Olá! Aqui é o atendimento."}'

Corre una rutina cada pocos minutos que liste las instancias y consulte el estado de cada una. Si algún número deja de estar conectado, registra la hora, avisa a la persona responsable y, si es una desconexión, ofrece un nuevo código QR. Guarda el historial de estados para ver patrones, como un número que se cae todos los días a la misma hora.

Sigue también la tasa de respuesta por número y el límite de conversaciones nuevas, que informa el endpoint de límites. Un número con respuestas en caída es candidato a pausa antes de volverse un problema. La referencia de los endpoints está en la documentación de la API.

const list = await call("GET", "/instances");

for (const inst of list) {
  const s = await call("GET", "/" + inst.id + "/instance/status");
  const status = s.instance.status;
  if (status !== "connected") {
    console.warn("instance down:", inst.name, status);
  }
}

En ZapZap cada número activo cuesta R$15 al mes, prepago, sin cobro por mensaje; el valor vigente está en precios. Como el costo es por número, el costo de la multiinstancia es predecible: suma los números y multiplica. La creación cobra tarifa de activación y proporcional, que el endpoint de costo muestra antes de crear.

Un límite práctico es organizacional: sin nombres estandarizados y sin una tabla que una instancia con dueño, el sistema se vuelve un desorden con pocos números. Estandariza el nombre (cliente, función, número) y revisa cada mes qué instancias siguen en uso. Quien llegue a muchos números también debe planear la contingencia de la guía número bloqueado: qué hacer.

Los errores más frecuentes son usar el ID de instancia equivocado en la ruta, mezclar clientes en el mismo número, olvidar actualizar la tabla cuando se cambia un número, dejar el secreto del webhook en código público y no monitorear las caídas. Todos se resuelven con nombres estandarizados, una única tabla de verdad y alertas automáticas.