Para proteger a estabilidade da conexão e evitar bloqueios pelo WhatsApp, a plataforma aplica um controle automático de velocidade de envio nas conexões de API Não Oficial. Esse mecanismo é chamado de rate limit e define quantas mensagens podem ser disparadas por canal em um determinado intervalo de tempo.
Quando o limite é atingido, a plataforma não descarta a mensagem: ela é retida e reenviada automaticamente assim que o canal estiver liberado.
Qual é o limite de envio?
O limite varia conforme o tipo de mensagem enviada, já que mídias (imagem, vídeo, áudio e documento) exigem mais recursos de processamento do que mensagens de texto.
Exemplo prático: enviar 7 textos e 1 imagem já equivale ao limite máximo de um intervalo. A partir daí, o próximo envio aguarda o ciclo reiniciar.
O limite é por canal: cada número de WhatsApp conectado à plataforma tem sua própria contagem independente. Operações com múltiplos canais não interferem umas nas outras.
O que acontece quando o limite é atingido?
Ao atingir o limite, o canal recebe um bloqueio temporário. A plataforma detecta isso automaticamente e inicia um ciclo de retentativas progressivas, aumentando o intervalo de espera a cada nova tentativa para não sobrecarregar o canal.
Esse processo ocorre de forma totalmente automática e invisível para o atendente. A mensagem permanece na fila interna até ser entregue com sucesso.
O que é o erro H522?
Se após 1 hora de retentativas a mensagem ainda não conseguiu ser enviada, a plataforma considera que o canal não tem capacidade de entregar aquela mensagem e encerra o processo.
Nesse caso:
-
A mensagem é marcada com status de Falha
-
O erro H522 é registrado com a descrição: “A quantidade de disparos excedeu a capacidade do canal”
-
O atendente ou administrador pode visualizar esse detalhe no histórico da conversa
O erro H522 não é recuperável automaticamente. Caso ele ocorra com frequência, é recomendável revisar o volume de disparos ou distribuir o envio entre mais canais.
Como evitar atingir o limite?
-
Espace os disparos em campanhas: ao configurar envios em massa, utilize intervalos entre as mensagens para não saturar o canal.
-
Prefira texto quando possível: mensagens de texto consomem menos capacidade do que mídias.
-
Use múltiplos canais: distribua os envios entre diferentes números de WhatsApp para aumentar a capacidade total.
-
Detalhes Técnicos
Esta seção descreve como o mecanismo de rate limit funciona internamente.
Configuração do Rate Limit
Peso por tipo de mensagem
Como o limite é calculado
O sistema utiliza uma janela deslizante com média:
-
A cada envio, o sistema analisa os últimos 30 segundos divididos em 3 janelas de 10 segundos
-
Calcula a média de pontos consumidos nessas 3 janelas
-
Se a média for ≥ 10 pontos, a mensagem é bloqueada
-
Se a média for inferior, o envio é registrado e o contador incrementa com o peso do tipo daquela mensagem
Há também uma detecção rápida: se a janela atual já acumulou 10 pontos ou mais, o bloqueio ocorre imediatamente, sem calcular a média.
Backoff progressivo das retentativas
O intervalo de espera entre cada tentativa cresce progressivamente conforme a fórmula abaixo:
Após 1 hora sem sucesso, o sistema encerra as tentativas e registra o erro H522 com status FAILED na mensagem.
Este artigo explica por que algumas mensagens recebidas aparecem como “Aguardando Mensagem” ou “waitingMessage” na plataforma e como resolver esse problema.
Como resolver
O procedimento abaixo força uma nova sincronização das chaves de criptografia entre o WhatsApp e a plataforma, normalizando o recebimento das mensagens.
Passo 1: Desconecte todas as conexões ativas do WhatsApp
Acesse a plataforma, vá até Ajustes > Conta > Canais de Atendimento e desconecte o número afetado.
Passo 2: Atualize o aplicativo WhatsApp
No celular, verifique se o aplicativo WhatsApp Business está atualizado para a versão mais recente disponível na loja de aplicativos (App Store ou Google Play).
Passo 3: Reconecte o número à plataforma
Após atualizar o app, acesse novamente Ajustes > Conta > Canais de Atendimento e realize a reconexão do número normalmente.
Passo 4: Valide a versão do WhatsApp do cliente final
Versões desatualizadas do WhatsApp no celular dos seus contatos também podem ocasionar esse problema. Oriente os clientes que apresentarem essa situação com frequência a manterem o aplicativo atualizado.
Considerações Finais
-
O procedimento de desconectar e reconectar o número é a forma recomendada de forçar a ressincronização das chaves de criptografia.
-
Mensagens que já foram recebidas como “waitingMessage” não serão recuperadas após a reconexão. O procedimento garante que novas mensagens sejam recebidas corretamente.
-
Se o problema persistir após seguir os passos acima, entre em contato com o suporte da plataforma.
O campo de Integridade funciona como um monitor de saúde em tempo real para a sua conexão de WhatsApp. Ele permite que os administradores saibam rapidamente se o canal está operando de forma correta ou se o sistema está lidando com alguma instabilidade técnica.
Para consultar o status atual, acesse o menu Ajustes > Conta > Canais de atendimento e clique em “Detalhes” no canal desejado.
Abaixo, explicamos o significado de cada um dos 4 níveis de integridade e como a plataforma reage em cada cenário para proteger a sua operação:
🟢 Estável
É o melhor cenário possível. Significa que a conexão entre a plataforma e o WhatsApp (ou o seu provedor) está funcionando perfeitamente, sem interrupções. O envio e o recebimento de mensagens estão ocorrendo em tempo real.
🟡 Verificando Conexão
O sistema atua de forma preventiva. Nesta fase, a nossa infraestrutura detectou uma potencial falha, atraso ou queda de conexão com o canal e iniciou uma verificação automática.
-
Impacto na operação: Para evitar alarmismo desnecessário devido a pequenas oscilações de rede, nenhum aviso é exibido para o atendente na tela de atendimento. A operação segue normalmente enquanto o sistema tenta resolver a falha em segundo plano.
🟠 Em Alerta
O problema foi confirmado e persiste. Como a verificação inicial não resolveu a instabilidade, a plataforma entra em modo de proteção de dados e começa a tentar ativamente reconectar o canal.
-
Impacto na operação: Os usuários passam a ver um aviso na interface informando que o sistema está tentando uma reconexão.
-
Fila de Segurança: Para garantir que nenhuma informação se perca, todas as mensagens enviadas pela equipe a partir deste momento são direcionadas para uma fila de espera protegida. Elas serão disparadas automaticamente assim que a conexão for restabelecida.
🔴 Crítico
A conexão falhou de forma severa ou prolongada. Este status indica que o canal está inoperante há algum tempo.
-
Impacto na operação: Os usuários recebem um alerta claro de que existe uma instabilidade grave no canal. As mensagens de saída continuam sendo retidas na fila de segurança.
-
Ação necessária: Neste estágio, geralmente é necessária a intervenção de um administrador. Pode ser preciso verificar se o número sofreu algum bloqueio na Meta ou reconectar o QR Code (no caso de canais não oficiais).
🛡️ Resumo da Proteção de Mensagens
A transição automática entre estes status foi desenhada para garantir que a sua equipe nunca perca o trabalho realizado.
Mesmo que o canal entre em estado de “Alerta” ou “Crítico”, o atendente pode continuar digitando e enviando as mensagens no chat; a plataforma irá guardá-las em segurança e entregá-las aos clientes na ordem correta assim que o status retornar para “Estável”.
Detalhes Técnicos
Esta seção descreve como o sistema de integridade funciona internamente.
Enum de Status
Internamente, o campo HealthStatus do canal utiliza o enum ChannelHealthStatus com os seguintes valores:
Mecanismo de Health Check (Circuit Breaker)
O health check é controlado por um job do Hangfire que roda com retentativas automáticas. O número de tentativas (RetryCount) determina o status atual:
A cada tentativa, o sistema aguarda a resposta do gateway por até 15 segundos (na primeira tentativa) ou 10 segundos (nas subsequentes).
Critério de saúde (canal ZAPI): o canal é considerado saudável quando:
-
Existe uma mensagem enviada com sucesso nos últimos 2 minutos
-
A instância do gateway está com status Connected
-
Todos os webhooks necessários estão inscritos
Recuperação automática
Quando o gateway responde com sucesso em qualquer tentativa:
-
O status é alterado para OK
-
As mensagens retidas na fila de segurança são reenfileiradas automaticamente para envio
-
A interface do utilizador é notificada em tempo real via WebSocket
Pausa automática de campanhas
Quando o status muda para ALERT, CRITICAL ou DISCONNECTED, todas as campanhas ativas associadas ao canal são pausadas automaticamente com a seguinte mensagem de motivo:
-
ALERT / CRITICAL: “O número [X] está com a conexão instável”
-
DISCONNECTED: “O número [X] está desconectado”
As campanhas permanecem pausadas até que um administrador as retome manualmente após a estabilização do canal.
Recentemente, o WhatsApp implementou uma atualização significativa em suas políticas de privacidade, alterando a forma como os números de telefone são exibidos em novas conversas através da introdução de um identificador chamado LID. Essa mudança pode, em alguns casos, gerar dúvidas e ocasionar a criação de contatos duplicados na plataforma.
Esta documentação tem como objetivo explicar o que é o LID, por que ele ocorre e orientar você sobre o procedimento correto para gerenciar e unificar esses contatos, garantindo a integridade do seu histórico de atendimento.
1. O que é o “LID” e por que ele aparece?
O LID é um identificador alfanumérico temporário que o WhatsApp utiliza para proteger a privacidade dos usuários em novas conversas. Isso ocorre especialmente em dois cenários:
-
Quando o cliente inicia o contato e possui configurações de privacidade restritas.
-
Quando o canal de atendimento inicia o atendimento com o contato diretamente pelo aplicativo do WhatsApp (celular) ao invés de usar a plataforma.
Comportamento: Ao receber uma mensagem de um número desconhecido ou restrito, a plataforma pode não receber o telefone de imediato, exibindo o LID no lugar do nome (Ex: [NOVO] 45114384841704@lid).
Comportamento da plataforma: Nosso sistema exibe o LID que recebe no campo de nome do contato. Assim que o cliente interage e o WhatsApp libera o número real, o sistema automaticamente cria (ou atualiza) o contato com o número correto.
Consequência: Isso cria um contato provisório na sua base. Se você já tinha esse cliente salvo anteriormente com o telefone real, o sistema pode acabar ficando com dois registros: o antigo (com telefone) e o novo (com LID).
⚠️ Importante
Enquanto o sistema tiver apenas o LID, não é possível responder à conversa, pois a plataforma ainda não possui o número de telefone para o qual enviar a mensagem.
2. Como Unificar Contatos (Resolvendo o LID)
A forma mais eficiente de resolver a fragmentação (ter um contato LID e um contato real para a mesma pessoa) é através da Edição e Mesclagem.
O sistema identifica automaticamente se o dado que você está inserindo pertence a outro contato e sugere a unificação dos históricos.
Passo a Passo para Mesclar:
-
Acesse o Contato Provisório (LID): Abra a conversa ou a ficha do contato (CRM -> Contatos) que está identificado apenas pelo código LID (o registro novo/duplicado).
-
Edite o Contato: Clique no botão de Editar (ícone de lápis) nos dados do contato.
-
Insira o Dado Chave: No campo Telefone, digite o número real do cliente.
-
Detecção Automática: Ao tentar salvar, o sistema identificará que esse telefone já pertence ao cadastro antigo do seu cliente.
-
Assistente de Mesclagem: Em vez de bloquear, o sistema abrirá automaticamente o modal “Contato semelhante já existente”, perguntando se você deseja revisar as informações
-
Confirmação: Clique em Revisar para prosseguir.
Isso garante que você não perca nenhuma mensagem e centralize toda a comunicação em um único perfil organizado.
3. Perguntas Frequentes Adicionais
-
A mesclagem automática não funcionou. Por quê? A função automática de “Mesclar” depende de uma correspondência exata de dados técnicos que nem sempre o WhatsApp fornece. Por isso, o método manual descrito acima (Editando e inserindo o telefone) é a forma mais segura e garantida de forçar a unificação.
-
Isso acontece na API Oficial (WABA)? Não. Esse comportamento é característico de conexões via QR Code (Z-API/Não Oficiais). A API Oficial do WhatsApp (Cloud API) recebe sempre o número de telefone como identificador único, evitando a criação de duplicatas por LID.
