{"id":765,"date":"2026-10-29T13:24:34","date_gmt":"2026-10-29T13:24:34","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/mensagem-nao-entregue-api-whatsapp\/"},"modified":"2026-10-29T13:24:45","modified_gmt":"2026-10-29T13:24:45","slug":"mensagem-nao-entregue-api-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/mensagem-nao-entregue-api-whatsapp\/","title":{"rendered":"Mensagem enviada mas n\u00e3o entregue na API do WhatsApp: checklist de diagn\u00f3stico"},"content":{"rendered":"\n

Atualizado em 29\/10\/2026<\/em><\/p>\n\n\n\n

Quando a API do WhatsApp aceita a mensagem mas ela n\u00e3o chega, a resposta est\u00e1 no webhook de status: ou a mensagem ficou parada em sent<\/code> (saiu dos servidores da Meta, mas n\u00e3o chegou ao aparelho) ou terminou em failed<\/code> com um c\u00f3digo de erro. No primeiro caso, as causas mais comuns s\u00e3o cliente offline, n\u00famero bloqueado pelo cliente ou pa\u00eds com restri\u00e7\u00e3o; no segundo, o c\u00f3digo diz o que aconteceu e se vale reenviar. A Meta s\u00f3 cobra mensagens entregues, ent\u00e3o uma mensagem que n\u00e3o chegou n\u00e3o entra na fatura.<\/p>\n\n\n\n

Este checklist parte do sintoma que voc\u00ea v\u00ea no seu sistema e chega \u00e0 a\u00e7\u00e3o. Para a refer\u00eancia completa de c\u00f3digos, veja o guia de erros da API do WhatsApp<\/a>.<\/p>\n\n\n\n

Passo 1: confirme que a API aceitou a mensagem<\/h2>\n\n\n\n

Antes de falar em entrega, confira a resposta s\u00edncrona do envio. Se a chamada devolveu um objeto error<\/code>, a mensagem nem saiu: o problema \u00e9 de token, par\u00e2metro, template ou limite de chamadas, e n\u00e3o de entrega. Se devolveu 200<\/code> com um wamid<\/code>, a mensagem foi aceita:<\/p>\n\n\n\n

{\n  \"messaging_product\": \"whatsapp\",\n  \"contacts\": [{ \"input\": \"5511999999999\", \"wa_id\": \"5511999999999\" }],\n  \"messages\": [{ \"id\": \"wamid.HBgLNTUxMTk5OTk5OTk5...\" }]\n}<\/code><\/pre>\n\n\n\n
Guarde esse wamid<\/code>. \u00c9 por ele que voc\u00ea liga cada evento de status \u00e0 mensagem original. Sem ele no banco, o diagn\u00f3stico vira adivinha\u00e7\u00e3o.<\/p>\n\n\n\n
Passo 2: leia o status no webhook<\/h2>\n\n\n\n
A partir daqui, tudo chega pelo webhook messages<\/code>, no array statuses<\/code>. A refer\u00eancia de status da Meta<\/a> define cinco valores:<\/p>\n\n\n\n
Status<\/th>O que a Meta diz<\/th>O que significa para o diagn\u00f3stico<\/th><\/tr><\/thead>
sent<\/code><\/td>A mensagem saiu dos servidores da Meta<\/td>Aceita e despachada, mas ainda n\u00e3o chegou ao aparelho<\/td><\/tr>
delivered<\/code><\/td>Entregue no aparelho do usu\u00e1rio<\/td>Chegou; a partir daqui \u00e9 cobr\u00e1vel<\/td><\/tr>
read<\/code><\/td>Exibida numa conversa aberta no aparelho<\/td>Lida (s\u00f3 conta como lida se foi entregue)<\/td><\/tr>
played<\/code><\/td>Primeira reprodu\u00e7\u00e3o de uma mensagem de voz<\/td>S\u00f3 para \u00e1udio de voz<\/td><\/tr>
failed<\/code><\/td>Falha ao enviar ou entregar<\/td>Veja o array errors<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Dois detalhes evitam alarme falso. Primeiro, se o usu\u00e1rio l\u00ea a mensagem na hora, a Meta pode n\u00e3o mandar o delivered<\/code>, porque o read<\/code> j\u00e1 implica a entrega. Ent\u00e3o “n\u00e3o recebi delivered” n\u00e3o quer dizer “n\u00e3o foi entregue” quando existe read<\/code>. Segundo, se o webhook n\u00e3o est\u00e1 chegando de jeito nenhum, o problema \u00e9 outro: revise a configura\u00e7\u00e3o descrita no guia de webhooks da API do WhatsApp<\/a> antes de culpar a entrega.<\/p>\n\n\n\n
O guia de status de mensagem via webhook<\/a> mostra como gravar esses eventos. Aqui o foco \u00e9 o que fazer quando eles mostram um problema.<\/p>\n\n\n\n
Passo 3: mensagem parada em sent<\/code><\/h2>\n\n\n\n
Este \u00e9 o caso mais confuso: nada de erro, mas tamb\u00e9m nada de delivered<\/code>. A p\u00e1gina de suporte da Cloud API<\/a> lista as causas mais comuns:<\/p>\n\n\n\n