Ir para o conteúdo

Como consultar status de envio de mensagens

Conforme explicado na documentação Assincronicidade no envio de mensagens, o envio de mensagens para contatos através da WhatsApp Business API acontece de forma assíncrona. Sendo assim a consulta ao status poderá não trazer resultados se ocorrer de forma imediata após a solicitação de envio. Recomendamos esperar alguns segundos e tentar novamente depois de um tempo caso a consulta não traga nenhum resultado.

1. Primeiro passo - Obter credenciais de acesso

Antes de consultar o status de solicitações de envio de mensagens, a aplicação cliente deve obter o token de acesso às APIs, conforme descrito no guia Como autenticar.

2. Segundo passo - Consultar status de envio de mensagens

Para consultar o status deve-se fazer uma requisição HTTP GET para o endpoint https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/{id}, conforme exemplo abaixo:

ID_REQUISICAO

Este deve ser o valor do id da requisição, recebido como resposta do serviço de envio de mensagens.

Exemplo com curl

Exemplo com curl

curl -v --request GET \
  --url 'https://api.whatsapp.serpro.gov.br/client/{fromPhoneNumberId}/v2/requisicao/{id}' \
  --header 'Authorization: Bearer VALOR_TOKEN'

3. Terceiro passo - Resultado da consulta de status de envio de mensagens

A resposta do serviço de consulta de status de envio de mensagens é um objeto json. Alguns campos da resposta são relacionados ao pacote de requisições, enquanto os outros campos são relacionados ao status de envio das mensagens em si.

Campos da resposta

Campos relacionados ao pacote de requisições:

fromPhoneNumberId, nomeTemplate, quantidadeMensagens, destinatarios

Campos relacionados aos status de envio das mensagens:

requisicoesEnvio, aguardandoEnvio

No exemplo de payload de resposta abaixo temos os status de envio de mensagens do pacote de requisições com id ee54a0d5-c0af-441d-a7eb-55b0ab24625, contendo status de envio das mensagens para os contatos CONTATO_1 e CONTATO_2.

{
    "fromPhoneNumberId": "FROM_PHONE_NUMBER_ID",
    "nomeTemplate": "exemplo_de_confirmao_de_envio", 
    "timestampRecebimentoPacote": "1676461389940",
    "idRequisicao": "ee54a0d5-c0af-441d-a7eb-55b0ab24625a", 
    "quantidadeMensagens": 1,
    "destinatarios": [ "CONTATO_1", "CONTATO_2"],
    "requisicoesEnvio": [
        { 
            "idMeta": "wamid.HBgNNTUyMTk5ODUxMTMyNBUCABEYEkYzNzk5MTM0ODNGMTg5QTRBNgA=",
            "destinatario": "CONTATO_1", 
            "sucessoEnvioApi": true,
            "timestampEnvioApi": "1676461392971",
            "timestampProcessamentoStatusApi": "1676461394024",
            "mensagemErro": null,
            "sent": "1676461392",
            "delivered": "1676461393",
            "deleted": null,
            "failed": null,
            "read": "1676461436",
            "failedErrors": null
        }
        ],
    "aguardandoEnvio":[]
}

Informações dos status de envio das mensagens

Na resposta da consulta ao status de um pacote de requisições, o atributo requisicoesEnvio contém uma lista com status de envio de mensagens para cada contato individual. Alguns atributos se referem ao status definido pela WhatsApp Business API ao chamar o serviço da Cloud API da Meta, quanto outros atributos se referem a status recebidos da própria Meta. Estes últimos contém informações mais precisas a respeito do status.

Integração com serviço da Cloud API da Meta

  • idMeta: identificador da mensagem na Meta.
  • sucessoEnvioApi: houve sucesso na chamada ao serviço da Meta para envio de mensagem. Significa que o pedido de envio foi internalizado na Meta e os status recebidos da Meta devem ser checados para saber o que de fato aconteceu
  • mensagemErro: houve um erro na chamada ao serviço da Meta e a mensagem não será enviada. Este campo contém o erro em questão

Status recebidos da Meta

  • sent: momento em que a mensagem foi de fato enviada pela Meta para o contato
  • delivered: mometo em que o aplicativo do contato recebeu a mensagem
  • read: momento em que o contato leu a mensagem
  • deleted: momento em que o contato apagou a mensagem
  • failed: falha no envio da mensagem ao contato pela Meta. Este atributo é muito importante, pois ele pode informar um erro ocorrido no processo interno da Meta e a mensagem não foi enviada, mesmo que o campo sucessoEnvioApi esteja com valor true. Caso o sent esteja preenchido, o failed ocorreu, mas foi resolvido e o envio da mensagem foi realizado.
  • failedErrors: Array contendo os objetos de erros enviados pela Meta. Normalmente apenas 1 erro é enviado. Formato: 
    "failedErrors": [
    {
        "code": "131026",
        "details": "Message Undeliverable."
    }
]

Resumo de como identificar os erros

Se o sucessoEnvioApi=False a meta não aceitou a requisição enviada. Texto do erro no campo mensagemErro. Se o failed estiver preenchido e o sent não estiver preenchido, ocorreu um erro no envio da mensagem pela meta. Detalhamento dos erros no campo failedErrors.