Skip to main content

​
Status da Mensagem

Após enviar uma mensagem e receber um id (por exemplo, msg_abc) de POST /v1/messages/send, consulte seu status atual. Para listar e filtrar muitas mensagens (enviadas e recebidas), veja GET /v1/messages.
Modal Detalhes do Log mostrando o balão da mensagem renderizada com botões de resposta rápida, nome do template, status Lida, data e hora, ID da mensagem com botão de copiar, variáveis e as ações Reenviar e Trace completo

Detalhes do Log no painel — a mensagem renderizada, o template, o status ao vivo (Lida) e o mesmo messageId que você consulta pela API.

{messageId} aceita o id interno da mensagem retornado pelo endpoint de envio, o correlationId ou o ID de mensagem do WhatsApp do provedor (wamid).
Em número oficial (Meta) este id também volta dentro do status nativo da Meta, em statuses[].biz_opaque_callback_data, então dá para ligar o status ao seu envio sem chamar este endpoint.

​
Exemplo

​
Resposta (200)

​
Um envio que falhou num número oficial

Uma mensagem livre enviada a um número oficial (Meta) depois que a janela de atendimento de 24 horas fechou. A Meta aceita a requisição e falha a mensagem depois, então ela tem wamid e sentAt. Não há a chave template porque o envio não usou template.
​
string | null
Motivo da falha legível por máquina, de um conjunto listado em Códigos de Erro do Log. É o mesmo valor que GET /v1/messages devolve para a mesma mensagem. null quando não há erro, e sempre null em DELIVERED, READ, PLAYED e CANCELED.Ramifique pelo errorCode, nunca pelo errorMessage. O errorMessage é texto para pessoas, e a redação dele não é contrato. O conjunto de códigos cresce, então trate um código que você não reconhece como “precisa de revisão”, e não como erro.Se o webhook de um envio nunca chegou, consulte este endpoint pelo id, pelo correlationId ou pelo wamid e classifique o resultado pelo errorCode.
​
string | null
O id da mensagem no provedor — num número oficial, o wamid da Meta. null até o provedor aceitar a mensagem, então continua null numa mensagem ainda QUEUED ou recusada antes de sair.
​
string
Nome do template com que a mensagem foi enviada. A chave é omitida, não null, quando o envio não usou template.
​
string | null
Por onde a mensagem saiu: API, MCP, CHATWOOT, CHAT, DASHBOARD, SYSTEM, ou null. Três tipos de mensagem enviada só aparecem em GET /v1/messages e não têm detalhe aqui (404), porque não foi a Pilot Status que as enviou: APP (app WhatsApp Business no celular, ou outra ferramenta na mesma WABA), LAYER (um cliente da camada Meta) e respostas CHATWOOT enviadas de uma inbox nativa WhatsApp Cloud. Uma resposta CHATWOOT vinda de uma inbox de espelho por API tem detalhe aqui.⚠️ null não significa “recebida”. Para isso, leia direction em GET /v1/messages. Um null numa linha OUT é saída não classificada — contá-la como entrada subconta os próprios envios num relatório de cobrança.
​
object | null
O veredito da própria Meta sobre o que foi cobrado nesta mensagem — conversationId, originType, category e type. null enquanto a Meta não reportar.type distingue regular (cobrada) de free_entry_point (janela aberta por clique em anúncio) e free_customer_service (dentro da franquia de serviço).
Não infira a categoria pelo template que enviou. A Meta recategoriza templates (template_category_update), e o mesmo envio cai como free_entry_point ou free_customer_service conforme a janela tenha aberto. Use o metaPricing acima.A mesma informação chega em tempo real no webhook, em pricing.category / pricing.type dentro de value.statuses[] do envelope nativo. O externalMessageId (o wamid) é o campo que junta os dois.
Mensagens enviadas pelo app do celular não recebem bloco de cobrança. As que chegam por smb_message_echoes recebem status de entregue e lida normalmente, mas o metaPricing fica null e o pricing nunca vem no webhook — medido em produção, sem exceção na amostra.Para um relatório de cobrança, conte-as à parte em vez de procurar um campo que não vem.

​
Status

Confirmações de leitura: o status READ e readAt só estão disponíveis quando o contato que recebeu a mensagem tem as confirmações de leitura ativadas no WhatsApp (Configurações > Privacidade > Confirmações de leitura). Caso contrário, o ciclo de vida pode parar em DELIVERED. O mesmo se aplica aos Logs e ao webhook message.read.
PLAYED é um valor novo. Ele é retornado em números oficiais (Meta Cloud API) para notas de voz (mediaType: "voice") quando o destinatário as ouve, e tem precedência acima de READ: uma mensagem que chega a PLAYED não volta para READ. Se a sua integração ramifica no status com um switch exaustivo ou uma lista fixa, inclua PLAYED antes que ele comece a aparecer — código que trata status desconhecido como erro vai encontrar um. Em números oficiais, mediaType: "audio" chega como arquivo de áudio, não como nota de voz, e não chega a PLAYED. Em números não oficiais, uma nota de voz ouvida aparece como READ.

​
Erros comuns

  • 401 — cabeçalho de chave de API ausente/inválido (x-api-key / x-api-key-id).
  • 404 — mensagem não encontrada dentro do escopo da chave.