Use este artigo quando o envio manual funciona, mas a mensagem enviada por automação, bot, API, webhook ou integração externa falha.

## O que normalmente muda nesse cenário

Quando um agente envia manualmente, a IAra usa o contexto visível da conversa. Quando uma automação ou API envia, o conteúdo depende de regra, payload, identificador do contato, estado da conversa e permissões do canal. Um erro pequeno em qualquer uma dessas partes pode impedir o envio.

## Diagnóstico rápido

1. Envie manualmente uma mensagem curta na mesma conversa.
2. Se manual falhar também, volte ao diagnóstico geral do canal.
3. Se manual funcionar, revise a regra, gatilho ou payload que gerou a mensagem.
4. Confirme se a conversa está aberta e elegível para receber aquela mensagem.
5. Confirme se o contato, conversa, caixa e canal usados são os corretos.
6. Remova variáveis, mídia e botões para testar conteúdo mínimo.
7. Se houver limite de envio, aplique intervalo entre tentativas.

## Erros comuns

| Família | Como aparece | Causa provável | Correção |
|---|---|---|---|
| API-400/422 | invalid payload, unprocessable entity, contato inválido, conversa inválida. | Campo obrigatório ausente, identificador incorreto ou conteúdo fora do formato. | Corrija payload, IDs e schema da integração. |
| API-CTX | Regra dispara, mas a mensagem não sai. | Automação fora do contexto real da conversa ou canal. | Ajuste condição, janela, time, status ou handoff. |
| API-WH | Evento não chega, status não atualiza ou bot não dispara. | Webhook/evento externo indisponível, inválido ou atrasado. | Revalide URL, autenticação, assinatura e resposta do endpoint. |
| GEN-006 | Conteúdo vazio, mídia inválida ou tipo não suportado. | Variável vazia, anexo incompatível ou componente inválido. | Defina fallback para variável vazia e teste texto simples. |
| GEN-007 | 429, rate limit, muitas tentativas. | Automação gerando volume alto ou repetido. | Reduza ritmo, deduplique gatilhos e use intervalo. |
| GEN-008 | 5xx, timeout ou instabilidade externa. | Provedor, webhook ou integração temporariamente indisponível. | Aguarde, aplique retry controlado e monitore recorrência. |

## Como diferenciar erro de canal e erro de automação

| Teste | Resultado | Interpretação |
|---|---|---|
| Manual falha e automação falha | Problema no canal, conta, contato ou política. | Investigue o canal antes da automação. |
| Manual funciona e automação falha | Problema de regra, payload, variável ou contexto. | Revise a automação/API. |
| Texto funciona e mídia falha | Problema de arquivo, URL, formato ou template com mídia. | Use o artigo de anexos e mídias. |
| Um contato falha e outro funciona | Destinatário, janela, bloqueio ou limite por contato. | Valide contato e política do canal. |

## Evidências para suporte ou implantação

- Nome da automação, bot, fluxo ou integração.
- Gatilho que deveria enviar a mensagem.
- Link da conversa e horário da tentativa.
- Conteúdo gerado pela automação.
- Variáveis usadas e valores reais preenchidos.
- Print do erro ou retorno da API.
- Confirmação se envio manual funciona na mesma conversa.