Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Webhooks de estado do WhatsApp: enviada, entregue, lida e falhada

Os webhooks de estado indicam o que aconteceu a uma mensagem que uma empresa enviou pela WhatsApp Cloud API. Chegam ao campo messages, com um array statuses em vez de um array messages: enviada (um visto), entregue (dois vistos), lida (dois vistos azuis), reproduzida nas mensagens de voz e falhada, com um array errors. Associe statuses[].id ao wamid devolvido pelo pedido de envio.

A easyCoexistence liga o número da app do WhatsApp Business que já usa à Cloud API da Meta através da Coexistence.

5

Valores de estado que a Meta envia: sent, delivered, read, played (primeira reprodução das mensagens de voz) e failed.

3

Webhooks de estado separados que uma mensagem enviada pode gerar: sent, delivered e read.

v24.0

A partir desta versão da Graph API, o objeto conversation é omitido, exceto nas mensagens numa janela de ponto de entrada gratuita.

0

Não existem APIs para obter dados de webhooks anteriores; a Meta pede que os payloads sejam capturados e guardados à medida que chegam.

messages

O cabeçalho X-EC-Event num estado reencaminhado: os estados viajam dentro de eventos messages, em value.statuses.

Onde chegam os webhooks de estado do WhatsApp?

No mesmo campo messages que transporta o que os clientes enviam, no mesmo envelope de objeto, entry e changes. A diferença está dentro de value: uma mensagem recebida tem um array messages, um estado tem um array statuses. Um handler que lê apenas value.messages descarta todos os estados sem qualquer erro. metadata.phone_number_id indica qual dos seus números enviou a mensagem, e vem acompanhado de um array contacts com o nome de perfil do cliente, o wa_id e o BSUID, exceto nos estados failed e no estado sent de mensagens de grupo. Este é o exemplo que a Meta dá de um template de marketing que saiu dos servidores da Meta:

Meta's example: a marketing message with status sent
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M."
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

O que significa cada valor de estado?

Cada valor corresponde a uma marca que o cliente vê no WhatsApp. Um estado só é considerado lido depois de ter sido entregue, e quando um cliente recebe uma mensagem com a conversa já aberta, a Meta envia read sem um webhook delivered anterior, como otimização interna. Por isso, um sistema de seguimento deve aceitar read mesmo que delivered nunca tenha chegado, e deve tratar os estados por ordem de precedência, em vez de os esperar um a um numa sequência fixa.

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

Que campos tem um objeto de estado?

Menos do que uma mensagem, e vários são condicionais. A referência da Meta indica quando cada um está presente:

  • id: o wamid da mensagem que enviou, a chave para associar.
  • status e timestamp: o valor e a hora Unix em que o webhook foi acionado, como string.
  • recipient_id: o número de telefone ou o id do grupo; omitido quando enviou para um BSUID e o número não está disponível.
  • recipient_user_id: o BSUID do cliente; omitido num estado failed quando enviou para um número de telefone.
  • recipient_type e recipient_participant_id: apenas para mensagens enviadas para um grupo.
  • biz_opaque_callback_data: apenas quando o definiu no pedido de envio.
  • pricing: apenas nos estados sent e num dos estados delivered ou read. errors: apenas nos estados failed.

Como se associa um estado à mensagem enviada?

Pelo wamid. O pedido de envio responde com messages[0].id, e cada estado dessa mensagem traz o mesmo valor em statuses[].id. Guarde-o junto do seu registo quando envia e atualize o registo quando os estados chegarem, mantendo o estado mais alto atingido, para que um delivered tardio não substitua um read. Um estado cujo wamid não conhece foi enviado por outra coisa no número, como uma automação, e pode ser ignorado ou registado.

statuses.mjs: apply status webhooks to your sends (Node.js)
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };

// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
  for (const s of value.statuses ?? []) {
    const rec = sends.get(s.id); // the wamid your send request returned
    if (!rec) continue; // sent by something else, such as an automation
    if (s.status === "failed") {
      rec.status = "failed";
      rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
    } else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
      rec.status = s.status; // read arriving before delivered is fine; never step back
    }
    rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
  }
}

O que muda num número Coexistence?

Os estados descrevem o que foi enviado pela API: respostas das suas automações, mensagens que a sua IA enviou através de um conector MCP, e tudo o que o seu próprio código enviou. O que o proprietário escreve na app do WhatsApp Business chega ao software de outra forma, como smb_message_echoes, que a Meta documenta como o espelho das mensagens enviadas pela app. As mensagens trazidas na importação única do histórico têm o seu próprio estado dentro do webhook de histórico, com valores como delivered, read, played, pending e error.

Os estados seguem para onde segue o campo messages do número. Com um destino direto, a Meta publica-os diretamente no seu endpoint, porque messages é um campo que a Meta permite que um destino substitua. Com as automações ativadas e um Forward URL definido, chegam a esse URL como eventos messages.

Como é que a sua IA ou automação sabe se uma mensagem foi entregue?

Através do seu destino, não do envio. Quando um assistente chama send_template ou send_message, o resultado da ferramenta traz o wamid e indica que a Meta aceitou a mensagem; a entrega é confirmada mais tarde, no dispositivo do cliente, e comunicada como estado. A easyCoexistence não guarda histórico de estados para consultar, e nenhuma ferramenta MCP lê estados, por isso um agente que precise de confirmação de entrega deve enviar através do seu sistema ou ler os estados que o seu Forward URL recebe.

O mesmo vale para as automações: uma execução no separador Runs mostra o passo de resposta como concluído assim que a Meta aceita a mensagem, e uma falha comunicada depois aparece apenas como estado failed no seu destino.

Erros comuns

  • Procurar um campo statuses separado. Os estados chegam em messages, por isso um handler que lê apenas value.messages perde-os sem qualquer erro.
  • Exigir delivered antes de read. A Meta omite o webhook delivered quando a mensagem é lida no momento em que chega.
  • Tratar a resposta do envio como entrega. Um wamid significa que a Meta aceitou o pedido; uma falha pode chegar minutos depois como estado failed.
  • Identificar clientes apenas por recipient_id. Ele é omitido quando enviou para um BSUID e o número de telefone não está disponível; é recipient_user_id que traz o BSUID.
Fazer isto com a EasyCoexistence

Os estados do que as suas automações, a sua IA ou o seu código enviam chegam ao seu servidor: diretamente da Meta no modo direto, ou reencaminhados para o seu Forward URL e assinados com X-EC-Signature quando as automações estão ativadas, e não são guardados por predefinição. De US$ 9 a US$ 0,75 por número ligado por mês, a descer à medida que acrescenta números, com os primeiros 3 dias grátis.

Perguntas frequentes

Os webhooks de estado incluem o texto da mensagem?

Não. Um estado traz o wamid, o estado, o destinatário, as datas e, quando aplicável, o preço e os erros. Guarde a sua própria cópia do que enviou, associada ao wamid, se precisar de a mostrar junto do respetivo estado.

Posso obter estados antigos da Meta mais tarde?

Não. O guia de webhooks da Meta indica que não existem APIs para obter dados históricos de webhooks, por isso um estado que o seu endpoint não capturou perde-se quando a Meta deixa de tentar novamente, após até 7 dias.

Para que serve biz_opaque_callback_data?

É uma string que define ao enviar, como o id do seu pedido ou do seu ticket. A Meta devolve-a no array statuses dessa mensagem, para que possa associar um estado ao seu registo sem procurar antes o wamid.

Tenho de responder aos webhooks de estado com 200?

Sim, como qualquer POST de webhook. A Meta trata qualquer outra resposta como entrega falhada e volta a tentar, e é uma das formas de o mesmo estado lhe chegar duas vezes.

Continue a ler

Pronto para começar?

Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.

Começar período experimental gratuito

Verificado em