Fila de envio na API oficial do WhatsApp é o buffer que fica entre o seu sistema e a Cloud API da Meta, e ela existe porque a plataforma aplica três limites ao mesmo tempo: velocidade por número, ritmo por destinatário e volume diário por portfólio de negócios. A Cloud API da Meta aceita até 80 mensagens por segundo por número registrado, com upgrade automático para 1.000 mensagens por segundo quando o número qualifica para o nível superior. Na prática, isso significa que a fila não é detalhe técnico: é ela que decide se a sua campanha de 20 mil mensagens sai em poucos minutos ou trava no meio com erro de taxa.
Quem vende ou atende por WhatsApp no Brasil usando a plataforma oficial — direto pela Cloud API ou por um provedor que a encapsula — precisa dimensionar a fila antes de disparar qualquer volume grande. Este guia mostra os três limites, o que cada erro significa e um procedimento de reprocessamento que mantém a entrega estável.
Como a Meta limita o envio
Os três limites operam em camadas diferentes e falham de formas diferentes. O throughput diz respeito ao número de negócios: quantas mensagens por segundo ele aceita, somando envios e recebimentos, em qualquer tipo de mensagem. O messaging limit diz respeito ao portfólio: quantos clientes únicos você pode abordar fora da janela de atendimento de 24 horas. E o par número-cliente diz respeito ao destinatário: com que ritmo a mesma pessoa pode receber mensagens suas.
Um portfólio novo começa restrito a 250 clientes únicos por período de 24 horas, e esse teto vale para todos os números do portfólio juntos. Para subir, existe um caminho de escala: verificar a empresa, ou entregar 2.000 mensagens fora da janela de atendimento para clientes únicos em 30 dias usando templates bem avaliados. A partir daí, os níveis de 10.000, 100.000 e ilimitado sobem por escala automática, desde que a qualidade das mensagens se mantenha alta e o uso passe da metade do limite atual em uma janela de 7 dias.
| Limite | O que controla | Valor de partida | Como aumenta |
|---|---|---|---|
| Throughput por número | Mensagens por segundo aceitas pelo número | 80 por segundo | Upgrade automático até 1.000 por segundo |
| Par número-cliente | Ritmo para o mesmo destinatário | 1 mensagem a cada 6 segundos | Não aumenta; exige espaçamento |
| Messaging limit do portfólio | Clientes únicos fora da janela de atendimento | 250 por 24 horas | 2.000, 10.000, 100.000 e ilimitado via verificação e escala automática |
O erro 130429 na prática
Quando a fila empurra mais mensagens do que o número suporta, a resposta da API é o erro 130429: throughput de mensagens atingido, e nada é entregue até a vazão voltar ao permitido. O erro chega junto da própria requisição, de forma síncrona, e a mensagem recusada não recebe identificador — cabe ao seu sistema mantê-la na fila e tentar de novo depois, não descartá-la como se tivesse sido enviada. Provedores que encapsulam a API repassam o mesmo código, então a decisão de dosar a vazão continua sendo sua.
O diagnóstico começa por separar os códigos. O 130429 trava o número inteiro por excesso de vazão; o 131056 trava só um destinatário; e o 131048 é restrição de reputação, disparado por bloqueios e denúncias — nesse caso o problema é a audiência e o conteúdo, e acelerar a fila só piora. Manter a base limpa, com descadastro respeitado no WhatsApp, reduz denúncias e protege a vazão que você já conquistou.
O limite por destinatário
Para o mesmo cliente, a regra é uma mensagem a cada 6 segundos, cerca de 10 mensagens por minuto ou 600 por hora; passar desse ritmo devolve o erro 131056. Esse teto é independente do throughput: mesmo com um número elevado ao nível de mil mensagens por segundo, cada cliente individual continua recebendo no máximo uma mensagem a cada 6 segundos do seu número.
A plataforma tolera rajadas: até 45 mensagens em uma janela de 6 segundos para o mesmo destinatário, mas a rajada empresta da cota futura — depois de uma rajada de 20, espere cerca de 2 minutos antes de mandar mais para essa pessoa. O caso mais comum de estouro nem é campanha, é fluxo mal desenhado: resposta fragmentada em cinco mensagens curtas em vez de uma única, workers paralelos atendendo a mesma conversa e retry que reenvia imediatamente a mensagem que acabou de falhar.
Fila com reprocessamento em 6 passos
- Separe as filas por número e por destinatário. Um balde de tokens por par número-cliente, espaçando 6 segundos entre envios ao mesmo contato, e uma vazão global por número em torno de 80% do throughput declarado.
- Leia a resposta de cada envio de forma síncrona. Se vier 130429, pause a fila inteira daquele número; se vier 131056, pause só aquele destinatário e siga com os demais.
- Reprocesse com backoff exponencial. A própria documentação da Meta recomenda tentar de novo após 4^X segundos, começando com X=0 e aumentando X a cada falha, até o envio passar.
- Marque cada mensagem com um identificador antes do envio, para que um retry não gere mensagem duplicada para o cliente.
- Confirme pelo webhook de status. Só considere a mensagem entregue depois do evento delivered; falhas chegam como failed com código, e é esse código que alimenta a decisão de reprocessar ou descartar.
- Meça o resultado em reais. Velocidade de fila só importa se a conversão acompanha; o cálculo do ROI do atendimento no WhatsApp mostra se vale acelerar a operação ou limpar a base primeiro.
Webhooks, ordem e capacidade
A ordem de entrega não é garantida: quando você envia uma sequência de mensagens, a API não promete que elas chegam ao cliente na ordem dos requests. Para fluxos que dependem de sequência — boleto depois do resumo, confirmação depois da pergunta —, espere o webhook de delivered da mensagem anterior antes de enviar a próxima.
Do lado do recebimento, dimensione o seu servidor de webhooks para aguentar pelo menos o triplo do tráfego de saída, porque cada mensagem gera múltiplos eventos de status. E reaja rápido a falhas: a qualidade do número, que sustenta o throughput e o messaging limit, cai com bloqueios e denúncias, e uma fila saudável depende de saber na hora quando uma entrega falhou.
