Vários números de WhatsApp em um sistema: guia de multi-instância

Há três motivos recorrentes. O primeiro é isolamento de falha: se um número cai ou é restringido, só ele para. O segundo é separação de função, como atendimento, vendas e cobrança em números diferentes, o que também deixa a conversa mais clara para o cliente. O terceiro é o modelo de agência ou software house, em que cada cliente final tem o seu número e o seu histórico.

Separar não é uma forma de burlar limites. Distribuir um mesmo disparo frio por muitos números repete o padrão que gera denúncias e agrava o risco; leia a matriz de risco. Multi-instância serve para organizar e isolar, e não para multiplicar volume.

Cada instância tem um ID. O seu sistema precisa de uma tabela que liga esse ID ao dono do número. Um desenho mínimo:

Guarde as chaves da API (x-api-key e x-api-secret) no servidor, em variáveis de ambiente ou cofre de segredos. A autenticação é da conta, e o ID da instância vai no caminho de cada chamada, então um único par de chaves opera todos os números. Detalhes em autenticação.

A API de gestão tem endpoints para listar, criar, consultar e remover instâncias. Antes de criar, o endpoint de custo informa taxa de ativação, proporcional e saldo necessário, e a criação debita do saldo da conta. O nome aceita só letras, números, underline e hífen. Depois de criar, a instância fica pendente até o número ser pareado por QR code.

O fluxo típico em um onboarding automático: consultar custo, criar a instância, guardar o ID, buscar o QR code, exibir para o cliente ler, configurar o webhook e acompanhar o status até virar conectado. O trecho a seguir faz isso em Node.js 18 ou 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));

Configure para cada instância uma URL própria que carrega o ID, por exemplo /hooks/whatsapp/ seguido do ID. Assim, quando o evento chega, o seu servidor já sabe de qual número ele veio e a qual cliente pertence, sem depender de adivinhar pelo conteúdo. Valide a origem com um segredo seu na URL ou no cabeçalho, e responda 2xx rápido, deixando o processamento pesado para uma fila.

Confira o que está chegando com o endpoint de entregas recentes e o de erros do webhook, e teste a URL com o endpoint de teste. Vale ler o guia de receber mensagens por webhook e a página de webhooks. Para ferramentas de automação, a integração com n8n mostra o desenho com uma URL por fluxo.

O envio usa o ID da instância no caminho, então escolher o número de saída é escolher o ID. Mantenha no sistema uma regra explícita de roteamento: por cliente, por função ou por fila. Evite sorteio entre números para a mesma conversa, porque o cliente deve ver sempre o mesmo contato.

Em um fluxo de atendimento, a resposta sai da mesma instância que recebeu a mensagem. Em um fluxo de cobrança, sai da instância da função de cobrança. Documente essas regras no seu código, de forma que quem entra no time entenda sem perguntar.

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."}'

Rode uma rotina a cada poucos minutos que lista as instâncias e consulta o status de cada uma. Se algum número sair de conectado, registre o horário, avise a pessoa responsável e, se for desconexão, ofereça o novo QR code. Guarde o histórico de status para ver padrões, como um número que cai todo dia no mesmo horário.

Acompanhe também a taxa de resposta por número e o limite de novas conversas, que o endpoint de limites informa. Um número com respostas caindo é candidato a pausa antes de virar problema. A referência dos endpoints está na documentação da 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);
  }
}

No ZapZap, cada número ativo custa R$15 por mês, pré-pago, sem cobrança por mensagem; o valor vigente fica em preços. Como o custo é por número, o custo de multi-instância é previsível: some os números e multiplique. A criação cobra taxa de ativação e proporcional, que o endpoint de custo mostra antes de você criar.

Um limite prático é organizacional: sem nomes padronizados e sem tabela que ligue instância a dono, o sistema vira bagunça com poucos números. Padronize o nome (cliente, função, número) e revise mensalmente quais instâncias ainda estão em uso. Quem chega a muitos números também deve planejar o plano de contingência do guia número bloqueado: o que fazer.

Os erros mais frequentes são usar o ID da instância errada no caminho, misturar clientes no mesmo número, esquecer de atualizar a tabela quando um número é trocado, deixar o segredo do webhook em código público e não monitorar quedas. Todos se resolvem com padronização de nomes, uma tabela de verdade única e alertas automáticos.