Quando uma mensagem não consegue ser enviada, seja em uma campanha, em um follow-up, na resposta do agente ou em um envio manual, a Nuvia mostra a falha no próprio contexto do envio, com a causa em linguagem clara, o código do canal e, quando o reenvio é possível, um botão para tentar de novo. Este artigo explica onde essas falhas aparecem e como interpretá-las.
Na conversa: o card de falha
Quando uma mensagem disparada falha, ela aparece na conversa com um card vermelho. O card sempre traz três informações:
-
A causa, em linguagem clara — na primeira linha, depois do rótulo Não enviada. Exemplo: “Não enviada · A janela de 24h desta conversa expirou. Envie um template aprovado para reabrir o contato.”
-
A linha de identificação — logo abaixo, com o código do canal, a origem da falha e o horário: “Código 131047 · WhatsApp (Meta) · 10/08 14:32”. A origem é WhatsApp (Meta), LinkedIn ou Nuvia.
-
Ver detalhes técnicos — um link que expande o retorno cru do provedor, o status HTTP e o número do registro da falha, quando essas informações existem.
A causa é exibida no seu idioma (português, inglês ou espanhol) sempre que o código do canal é reconhecido pela Nuvia por exemplo: número fora da janela de 24h, limite de envio atingido, template pausado pela Meta, conta de LinkedIn desconectada ou pendência de cobrança na Meta.
O botão Tentar novamente
O botão Tentar novamente faz exatamente o mesmo que o campo de digitação da conversa. Por isso ele só aparece quando o reenvio realmente pode dar certo:
-
a mensagem que falhou é de texto (template e mídia não são reenviados por esse botão);
-
a conversa não está encerrada;
-
a conversa está dentro da janela de 24h do WhatsApp;
-
sua conta não está em período de testes vencido.
Se qualquer uma dessas condições não for atendida, o botão não é exibido, o envio falharia de novo pelo mesmo motivo.
Bloqueio de janela de 24h: dois textos diferentes
Quando a Nuvia impede o envio porque não há janela aberta, o card explica qual das duas situações aconteceu:
| Situação | O que o card diz |
|---|---|
| O contato já respondeu em algum momento, mas as 24h passaram | “Janela de 24h expirada. Envie um template aprovado para reabrir a conversa.” |
| O contato nunca respondeu nessa conversa | “O contato ainda não respondeu, então não há janela de 24h aberta. Envie um template aprovado para iniciar a conversa.” |
Esse bloqueio é feito pela Nuvia, antes de a mensagem sair para o WhatsApp. Por isso ele aparece com origem Nuvia na linha de identificação — e não WhatsApp (Meta), como antes. A mudança separa o bloqueio nosso do erro 131047 de verdade, aquele em que a própria Meta recusa o envio.
Falha por variável de template vazia
Um caso comum de falha em campanhas de WhatsApp é o template que não pode ser enviado porque uma das variáveis mapeadas está vazia para aquele lead. Nesse caso, a mensagem indica exatamente qual campo preencher por exemplo:
O nome do campo aparece pelo rótulo amigável (ex: Nome da empresa), não pelo identificador técnico. Quando há mais de um campo vazio, todos são listados. Para entender como mapear variáveis e evitar campos vazios, veja Como usar variáveis em templates WhatsApp.
Contato que pediu para não receber marketing
Antes de enviar um template de Marketing, a Nuvia confere se aquele contato pode receber esse tipo de mensagem agora. Se não puder, o envio é bloqueado antes de sair para o WhatsApp e a falha aparece com origem Nuvia e o código MARKETING_SUPPRESSED.
São duas situações diferentes, com textos diferentes no card:
| Situação | O que o card diz | Quanto tempo dura |
|---|---|---|
| O contato pediu para parar de receber marketing | “Este contato pediu para não receber mensagens de marketing neste canal.” | Sem prazo — vale até o contato voltar atrás |
| O WhatsApp está limitando marketing para aquele contato | “O WhatsApp está limitando mensagens de marketing para este contato no momento. O envio será liberado automaticamente.” | 24 horas, e libera sozinho |
De onde vem o pedido de parar: o contato desativou as mensagens de marketing da sua empresa no próprio aplicativo do WhatsApp, ou a Meta recusou um envio com o código 131050 (o contato bloqueou marketing). Nos dois casos a Nuvia registra a preferência no contato e para de enviar marketing para ele naquele canal.
De onde vem o limite temporário: a Meta recusou um envio com o código 131049 (limite de mensagens de marketing por usuário) ou 130472. A Nuvia guarda esse bloqueio por 24 horas para aquele contato, naquele canal, dentro da sua empresa — e volta a enviar sozinha quando o prazo passa.
O 131049 tem dois momentos diferentes — e dois cards diferentes
Vale entender essa diferença, porque ela explica por que o mesmo problema aparece de duas formas na tela:
| Momento | O que aconteceu | Como aparece na conversa |
|---|---|---|
| A primeira recusa | O WhatsApp aceitou o envio, criou a mensagem e só depois avisou que não entregou | Origem WhatsApp (Meta), código 131049, com o texto “Não entregue: a Meta limita mensagens de marketing por usuário. Tente novamente em 24h.” |
| Os envios seguintes, dentro das 24h | A Nuvia já sabe do limite e nem chama o WhatsApp | Origem Nuvia, código MARKETING_SUPPRESSED, com o texto “O WhatsApp está limitando mensagens de marketing para este contato no momento. O envio será liberado automaticamente.” |
Na campanha: causas por etapa e Histórico de ações
No detalhe da campanha, o indicador de Falhas de cada etapa pode ser expandido para ver as causas agrupadas, a mensagem em linguagem clara, o código do canal e a quantidade de cada causa.
No Histórico de ações da campanha, cada execução que falhou mostra a mesma causa e a mesma linha de identificação (código e origem) que você vê no card da conversa. As duas telas usam a mesma tradução: o mesmo código nunca aparece com textos diferentes em lugares diferentes.
Na exportação de contatos da campanha
A exportação de contatos da campanha traz duas colunas com o motivo, logo depois da coluna Status:
-
Código do erro — o mesmo código que aparece no card (ex:
131049,131026) -
Motivo do erro — a causa em linguagem clara, igual à da tela
Antes a exportação só dizia “Erro de entrega” na coluna Status, sem dizer por quê. Agora você consegue filtrar a planilha por motivo e separar, por exemplo, “número não usa WhatsApp” de “limite de marketing”.
No webhook de saída
Se você usa os webhooks da Nuvia para acompanhar disparos em outro sistema, existe o evento MESSAGE_FAILED. Ele leva um campo failure_reason com o código, a causa em texto, a classificação e o provedor — o mesmo texto que o operador lê na conversa, não o retorno cru do canal.
Veja também Como interpretar as métricas de campanha.
Na integração com o HubSpot: Histórico de Sincronização
Quando a falha é do HubSpot, e não de um envio de mensagem, ela aparece no Histórico de Sincronização da integração. No detalhe do item com erro, a Nuvia mostra primeiro a causa classificada com o código do HubSpot (por exemplo INVALID_OPTION ou INVALID_PHONE_NUMBER), nomeando a propriedade que falhou, e só abaixo o retorno cru da API que pode passar de dois mil caracteres.
Itens de sincronização antigos, gravados antes dessa mudança, continuam exibindo apenas o retorno cru.
Falhas permanentes e transientes
Toda falha de envio é classificada internamente em dois tipos, o que ajuda a entender se você precisa agir:
-
Permanente — a Meta (ou a Nuvia) recusou esta tentativa. Normalmente é definitivo e pede uma ação sua: reconectar um número de WhatsApp, ajustar uma permissão, reconectar a conta de LinkedIn ou corrigir os dados do lead
-
Transiente — falha temporária, em que o reenvio acontece automaticamente (ex: limite de envio momentâneo, instabilidade do canal). Nesses casos a própria mensagem avisa que o reenvio é automático e que você não precisa fazer nada
O que a campanha reenvia e o que ela encerra na hora
Quando uma etapa de campanha falha, a Nuvia pode tentar o envio mais uma vez, cerca de 24 horas depois. É uma tentativa extra, não um ciclo infinito: se a segunda também falhar, o contato é encerrado naquela campanha.
Esse reenvio só é descartado quando a espera não muda nada — ou quando insistir seria errado.
A campanha reenvia em 24h:
-
131049 e 130472 — limite de mensagens de marketing por usuário. É uma janela do destinatário e passa sozinha
-
Limites e instabilidade momentânea do WhatsApp (130429, 131048, 131056, 131000, 132069 e afins)
-
Códigos que a Nuvia não reconhece e erros internos da própria plataforma
A campanha encerra o contato na hora, sem reenviar:
-
131026 — o número não usa WhatsApp. Não recupera nunca
-
131050 — o contato pediu para não receber marketing. Não se insiste, por política e não por eficácia
-
Erros de template (132000, 132001, 132015, 132016 e os outros 132xxx) — o problema está no template, não no momento
-
Conexão e configuração do número (0, 190, 3, 10, 200, 131031, 131037, 131042, 131045, 133010) — só sai depois que alguém arrumar
-
Janela e conteúdo (131047 janela expirada, 131051 tipo de conteúdo, 131052 e 131053 anexo, 131008 e 131009 variável faltando, 131021 próprio número do canal)
-
Bloqueios da própria Nuvia —
MARKETING_SUPPRESSEDe caixa de entrada sem agente padrão
Anexo recusado pela Meta (código 131053)
O código 131053 passou a ser tratado como falha permanente, com o texto “A Meta recusou o anexo. Tente enviar novamente.”
Antes ele aparecia como transiente e prometia reenvio automático — mas esse erro chega por aviso da Meta depois de o envio já ter sido aceito, então nenhum reenvio automático da plataforma alcança essa mensagem. O anexo simplesmente ficava pelo caminho e ninguém era avisado. Agora o card pede a ação: envie o anexo de novo.