Quando uma mensagem termina, inspecione o evento terminal e o código de erro antes de decidir se deve tentar novamente ou investigar a entrega.
O que significa whatsapp.rejected?
Bird interrompeu a mensagem antes do despacho e não a cobrou.
Verificações de destinatário e cobrança podem produzir um resultado de rejeição. Use o código que acompanha para escolher a próxima ação:
| Código | Causa | Próxima ação |
|---|---|---|
undeliverable | Nenhum endereço de destinatário utilizável | Corrija o destinatário |
recipient_suppressed | O destinatário está suprimido | Respeite o opt-out e investigue os registros de consentimento |
price_not_found | Bird não consegue precificar o envio | Entre em contato com o suporte com o identificador da mensagem |
insufficient_balance | A carteira não pode financiar o envio ou a organização não pode ser cobrada | Resolva o faturamento antes de enviar novamente |
Um envio sem preço é recusado, não tratado como gratuito. Repetir a solicitação sem alterações não fornece o preço ausente.
O timestamp da rejeição usa o horário de aceitação original. Use-o de forma consistente nos relatórios para que o atraso na fila não mova a rejeição para um período de relatório posterior.
O que significa whatsapp.failed?
A mensagem falhou durante o envio ou a entrega, com a causa registrada nos detalhes do erro.
A Meta pode reportar uma falha por meio de um callback de entrega. Ela também pode recusar a solicitação de envio de Bird antes de aceitar a mensagem para entrega.
Bird registra internal_error quando o número de envio não tem credencial utilizável ou o processamento esgota suas tentativas. meta_error_code é o código de erro registrado pela Meta. Este código Bird não contém nenhum.
Um esgotamento de tentativas pode incluir erros de transporte ou falhas upstream. Não infira apenas por internal_error que a Meta nunca recebeu uma solicitação.
Verifique a descrição e a conexão do número de envio. Forneça ao suporte o identificador da mensagem quando a causa permanecer incerta.
Uma falha pode ocorrer após a cobrança. Inspecione o cost da mensagem em vez de assumir que todo envio malsucedido foi gratuito.
Por que undeliverable aparece em ambos os eventos?
Em uma rejeição, Bird não conseguiu endereçar o destinatário. Em uma falha, é o resultado normalizado de Bird para uma recusa da Meta.
O código de erro é mais amplo do que uma declaração de que o telefone não pode receber mensagens. Bird também usa undeliverable quando um código da Meta não tem um mapeamento mais específico.
Leia meta_error_code para o código registrado pela Meta e description para a explicação que o acompanha. Uma falha reportada sem detalhes de erro ainda recebe undeliverable.
Outros códigos de falha normalizados identificam problemas mais específicos:
| Código | O que investigar |
|---|---|
service_window_expired | Se conteúdo de formato livre foi enviado fora da janela de serviço |
rate_limited | Os limites de envio ou de destinatário da Meta |
media_rejected | O recurso de mídia que a Meta recusou |
internal_error | A falha de processamento ou envio registrada por Bird |
Preserve códigos desconhecidos nos seus logs. O conjunto de códigos pode crescer, então um valor desconhecido não deve invalidar um evento que de outra forma seria utilizável.
Como meu handler de eventos deve interpretar o resultado?
Faça a ramificação pelo tipo de evento e seu código de erro juntos.
Uma mensagem rejeitada não progride para um evento de envio. Uma mensagem com falha precisa dos detalhes do erro para distinguir uma falha interna da resposta da Meta.
Mantenha o status de entrega separado do engajamento. Um evento whatsapp.read registra uma leitura sem substituir o status de entrega da mensagem.
Bird emite seu próprio whatsapp.sent após o envio ser bem-sucedido. Ele não cria outro evento a partir do callback separado de status de envio da Meta.
A revisão de template usa um conjunto diferente de status. Inspecione o idioma do template quando a aprovação for o problema, em vez destes resultados de mensagem.
O que devo fazer antes de outro envio?
Corrija a causa registrada antes de enviar outra mensagem.
Para service_window_expired, use um template aprovado ou aguarde a mensagem do cliente reabrir a janela de serviço.
Para supressão, respeite a escolha do destinatário. Remover um opt-out ignoraria a preferência do destinatário e criaria um risco de conformidade.
Para um problema de faturamento ou conexão do remetente, resolva essa condição da conta primeiro. Preserve o identificador original da mensagem para que o suporte possa inspecionar a tentativa malsucedida.
Se o número ou a Conta Business estiver restrita ou banida, siga as etapas de restrições e recursos da conta antes de tentar novamente.
Para uma falha de transporte incerta, investigue antes de criar outra mensagem. Um novo envio pode duplicar uma solicitação cujo resultado não foi observado.
Em resumo
Uma rejeição não é cobrada.
Bird interrompe a mensagem antes do despacho quando verificações de destinatário ou cobrança impedem o envio.
Uma falha pode vir de Bird ou da Meta.
Inspecione o erro registrado antes de decidir onde investigar.
internal_errornão contém um código de erro da Meta.Interprete o evento e o código juntos.
undeliverableaparece em ambos os eventos. Seu significado depende de onde a mensagem parou.Escolha a recuperação com base na causa.
Corrija o problema de destinatário, conta, conteúdo ou timing antes de tentar outro envio. Preserve códigos desconhecidos para investigação.