Sending Pools (múltiplos números)

Sending Pool é como ter várias filas de atendimento: em vez de empurrar tudo por um número, o sistema divide as mensagens entre os números do grupo, automaticamente.

Em poucas palavras

Agrupa vários números ativos e escolhe qual envia cada mensagem.
Opcional, sem pool, continue usando instanceId como sempre.
Cada pool é oficial ou não oficial; não mistura os dois.
Útil em campanhas grandes, com proteção se um número falhar.

Modos de conexão: Modos de conexão.

Quando usar

Situação	Usar pool?
Campanhas grandes (milhares de mensagens)	Sim
Quer proteção se um número falhar	Sim
Volume baixo em um número só	Não precisa
Precisa sempre o mesmo remetente	Use `instanceId` (pool ignorado)

Sem pool configurado, nada muda no fluxo atual com instanceId.

Um tipo por pool

Esta é a regra principal:

Tipo do pool	Instâncias permitidas
Oficial	Só números com conexão oficial
Não oficial	Só números com conexão não oficial

O tipo do pool é definido pelo primeiro número que você adiciona (ou pela criação no painel). Toda instância nova no mesmo pool precisa ser do mesmo tipo.

Precisa dos dois modos? Crie dois pools (um oficial, um não oficial).
Tentar misturar na hora de adicionar → SENDING_POOL_KIND_MISMATCH
Pool já inconsistente no envio → SENDING_POOL_KIND_MIXED

Códigos completos: Respostas de erro.

Templates, regras de envio e risco são diferentes entre oficial e não oficial. Por isso o pool nunca cruza os modos.

Como funciona na prática

Crie o pool no painel e adicione números ativos do mesmo tipo
Escolha como distribuir (rodízio, peso ou menor uso do dia)
Envie sem instanceId, o pool padrão ou o sendingPoolId escolhe o número de cada destinatário
Se um número falhar demais, o circuit breaker pausa só ele; os outros seguem

Com instanceId explícito, a mensagem sai daquele número e o pool não entra naquele envio.

Modos de distribuição

Modo	Como funciona	Bom para
Rodízio	Número 1 manda N mensagens, depois número 2, e assim por diante	Chips com capacidade parecida
Por peso	Peso 3 envia ~3× mais que peso 1	Um número mais forte ou maduro
Menor uso	Sempre o que menos enviou hoje	Números que entram em horários diferentes

Configurações principais

Configuração	O que faz	Padrão
Trocar a cada N mensagens	Lote por número antes de trocar	50
Tempo de descanso (cooldown)	Pausa entre lotes	Nenhum
Monitorar saúde	Pausa número com muita falha	Sim
Limite de falhas	% de erro para pausar no pool	30%
Pool padrão	Usado quando omitir `instanceId`	Conforme painel

Por número: peso, limite diário, cooldown próprio e pausa manual. Se mais de 30% das mensagens de um número falharem em 10 minutos, ele é pausado só naquele pool (não desconecta o WhatsApp). Quando normalizar, volta sozinho.

Na API

Pool padrão (sem escolher número)

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

{
  "to": ["5511999999999", "5511888888888"],
  "type": "text",
  "payload": {
    "message": "Seu pedido foi confirmado!"
  }
}

Pool específico

{
  "to": ["5511999999999"],
  "type": "text",
  "sendingPoolId": "ID_DO_POOL",
  "payload": {
    "message": "Promoção da semana!"
  }
}

Número fixo (ignora pool)

{
  "instanceId": "ID_DA_INSTANCIA",
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Mensagem por este número."
  }
}

Não envie instanceId e sendingPoolId juntos, a API responde 400.

Boas práticas

Aqueça números novos antes de campanha pesada: 200–500 mensagens/dia por chip no começo. Limite diário no painel ajuda.

Ative cooldown em envios grandes (ex.: 30 s a cada 50 mensagens)
Monitore no painel se algum número foi pausado pelo circuit breaker
Combine com Política anti-banimento

Próximos passos

Introdução: visão geral do canal
Quick Start: conectar e enviar
Modos de conexão: oficial × não oficial
Política anti-banimento: ritmo e aquecimento

​Em poucas palavras

​Quando usar

​Um tipo por pool

​Como funciona na prática

​Modos de distribuição

​Configurações principais

​Na API

​Pool padrão (sem escolher número)

​Pool específico

​Número fixo (ignora pool)

​Boas práticas

​Próximos passos

Em poucas palavras

Quando usar

Um tipo por pool

Como funciona na prática

Modos de distribuição

Configurações principais

Na API

Pool padrão (sem escolher número)

Pool específico

Número fixo (ignora pool)

Boas práticas

Próximos passos