Mensagens de Template

Sua conta precisa estar habilitada antes da primeira chamada. O contrato é publicado com antecedência para que você possa construir; a habilitação é por conta e nós a combinamos com você junto com o template e o número remetente.

Enquanto sua conta não estiver habilitada, cada chamada responde 422 com "type": "account_not_eligible" — sempre, e não de forma intermitente. Não é problema da sua requisição e nenhuma retentativa muda isso: é configuração do nosso lado, e a resposta diz isso com essas palavras em vez de esconder atrás de um erro genérico. Fale conosco para habilitá-la. Qualquer mudança no contrato é anunciada no Changelog.

accepted significa "a caminho", não "deu certo". O envio segue seu curso depois da resposta. Não leia isso como sucesso — consulte o endpoint de estado, que é onde ele se resolve contra a mensagem real. É o único caminho: os webhooks de /v1/webhooks emitem apenas eventos de pedido (order.created, order.status_changed), nenhum de entrega.

Configure o timeout do seu cliente em 35 segundos ou mais. O POST aguarda a chamada ao serviço de envio, que tem o seu próprio teto de 30 segundos. No caminho normal ele responde em menos de um segundo, mas esse é o caso típico e não uma garantia: um cliente com timeout de 5 ou 10 segundos abandona requests saudáveis que ainda estão em voo, e depois reporta falhas que nunca aconteceram.

Um 422 num reenvio merece uma olhada antes de descartar o evento. Se a primeira tentativa pode já ter saído, o evento não está perdido: corrija a forma do corpo e reenvie com o mesmo event_id, que continua seguro e devolve o estado real. Quando o 422 foi de conta, esse reenvio responde 200 com "status": "failed" — é o estado guardado da primeira tentativa, não um envio novo.

O event_id não é um identificador de rastreio. Se o seu sistema gera um id novo a cada tentativa HTTP, esse valor não serve como event_id: cada retentativa apareceria como um evento distinto e o cliente receberia o WhatsApp mais de uma vez. Para rastrear tentativas use o header X-Request-ID — veja Request IDs.

status_detail em um failed não é uma lista fechada e pode estar ausente. Pode ser uma recusa de conta (account_not_eligible, no_sender_number), um envio que não chegou a se completar (send_failed) ou que foi cancelado antes de ser tentado (send_cancelled), ou, quando o provedor recusa a entrega com um código, provider_error_<código> — por exemplo provider_error_131049. O código é o da Meta e o catálogo deles muda sem nos avisar, então não ramifique de forma exaustiva sobre este campo: decida pelo status, registre status_detail e trate qualquer valor desconhecido — ou ausente — como uma falha genérica.

Um accepted também pode trazer delivery_not_observable: o envio desse comerciante vive em uma instância própria que este deployment não consegue ler, então o status não vai se resolver a cada consulta — não é uma falha.

Envie o offset em occurred_at. Um valor sem fuso horário é lido como UTC. Se o seu sistema envia hora local do Peru (UTC-5), o evento envelhece 5 horas a mais contra uma janela de 6: um carrinho abandonado há duas horas computa como de sete horas e volta discarded com motivo stale — respondendo 200, sem erro e sem mensagem enviada.

Um 502 não significa mais "pode ser qualquer coisa". As recusas que dependem da sua conta ou do seu evento têm resposta própria: conta não habilitada e falta de número remetente são 422, uma conversa em pausa é 200 com "status": "discarded" e "status_detail": "paused", e uma chave repetida é 409. O que sobra no 502 é uma falha real do serviço interno de envio. Repita com backoff algumas poucas vezes; se persistir, pare de repetir e fale conosco.

Não existe um ambiente sandbox. O dashboard sempre cria keys do tipo live e não há um ambiente isolado atrás delas — veja Autenticação. O ambiente de teste desta integração se diferencia pelo telefone de destino, não pela credencial.