Status de entrega de mensagens

Esta documentação descreve como acompanhar o envio e a entrega das mensagens de template disparadas por um fluxo de conversa acionado através de um webhook de cliente.

O acompanhamento acontece em duas etapas:

1. Retorno (push), ao disparar o webhook, o integrador pode informar uma URL de callback. Cada mensagem de template enviada pelo fluxo acionado envia, para essa URL, o ID da mensagem no WhatsApp (waId).

2. Consulta (pull), com esse waId em mãos, o integrador consulta, a qualquer momento, o estado atual da mensagem pela API LiveChat 360, usando uma chave de API.

Sumário

1. Informando a URL de callback

2. O callback recebido

3. Consultando o status da mensagem

4. Vocabulário de status

5. Limitações

---

1. Informando a URL de callback

Basta incluir o campo messageIdCallbackUrl no primeiro nível do corpo enviado ao webhook do cliente:

POST https://hooks.atendeserver.com.br/{codigo-do-webhook}
Content-Type: application/json

{
  "liveChatClientWebhookVersion": "v2.0",
  "messageIdCallbackUrl": "https://sua-empresa.com.br/hooks/waid",
  "telefone": "5511999999999",
  "nome": "Maria Silva"
}

O campo é opcional. Regras:

• deve ser uma string começando com http:// ou https://;

• valores ausentes ou malformados são simplesmente ignorados, o webhook continua funcionando normalmente, apenas sem o retorno;

• só tem efeito quando o webhook está configurado para acionar um fluxo de conversa e esse fluxo envia uma mensagem de template.

2. O callback recebido

Para cada mensagem de template efetivamente enviada ao WhatsApp, disparamos:

POST {messageIdCallbackUrl}
Content-Type: application/json

{
  "waId": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjhGMTk0RUY3NUYzODY5RDU3AA=="
}

Observações:

• o disparo é fire-and-forget, com timeout de 10 segundos: se a sua URL estiver indisponível, a mensagem ao contato é enviada e registrada normalmente, apenas o retorno é perdido;

• o callback é enviado sempre que o WhatsApp aceita a mensagem e nos devolve um waId , este é justamente o propósito do retorno: mesmo que a mensagem falhe depois (o WhatsApp aceita e só mais tarde reporta falha, de forma assíncrona), você já terá o waId e poderá acompanhar essa mudança pela consulta de status (que passará a retornar failed);

• o callback não é enviado apenas quando a mensagem nunca chega a ser aceita pelo WhatsApp, ou seja, quando nenhum waId é gerado (template rejeitado na hora do envio, contato sem número de telefone, ou outros erros similares);

• envios idênticos repetidos ao mesmo webhook dentro de 30 segundos são deduplicados, nesse caso o fluxo é acionado uma única vez e você recebe um único callback.

3. Consultando o status da mensagem

A consulta é um recurso da API LiveChat 360 e segue todas as suas regras, autenticação, escopos, envelopes de resposta, limites de requisição e registro de uso. Consulte a documentação da API para os detalhes gerais; o essencial está resumido aqui.

GET https://app-api.atendeserver.com.br/v1/messages/{waId}
Authorization: Bearer SUA_CHAVE

Pré-requisitos:

• uma chave de API, criada no painel em API ▸ Chaves;

• o escopo messages com a operação read habilitado nessa chave.

curl -H "Authorization: Bearer $KEY" \
  "https://app-api.atendeserver.com.br/v1/messages/wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjhGMTk0RUY3NUYzODY5RDU3AA=="

Resposta 200 OK:

{
  "data": {
    "id": 88213,
    "wa_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjhGMTk0RUY3NUYzODY5RDU3AA==",
    "status": "delivered",
    "has_failed": false,
    "error_message": null,
    "created_at": "2026-07-21T14:02:11.000Z"
  }
}

Campo	Tipo	Descrição
id	inteiro	Identificador da mensagem no nosso sistema
wa_id	string	ID da mensagem no WhatsApp (o mesmo recebido no callback)
status	string	Estado atual da mensagem (ver seção 4)
has_failed	booleano	true quando o WhatsApp reportou falha
error_message	string | null	Descrição do erro, no formato "<código> - <título>"
created_at	data ISO 8601	Momento em que a mensagem foi registrada

Outras respostas, sempre no envelope de erros da API ({ "errors": [{ "field"?, "detail" }] }):

Código	Situação
400	waId não informado
401	Chave de API ausente, inválida, desativada ou revogada
403	A chave não possui o escopo messages (read)
404	Nenhuma mensagem encontrada para o waId informado
429	Limite de requisições excedido (120 por minuto por chave)

Se o waId contiver caracteres especiais, envie-o codificado (encodeURIComponent).

Duas consequências práticas de a consulta ser um recurso da API:

• A busca é restrita à sua conta. Um waId de outra conta retorna 404, exatamente como um waId inexistente.

• Toda consulta é registrada. Método, rota, código de status, duração e origem aparecem no painel em API ▸ Requisições, junto com as demais chamadas da chave.

4. Vocabulário de status

Status	Significado
pending	Mensagem registrada, ainda sem confirmação de envio do WhatsApp
sent	Enviada ao WhatsApp
delivered	Entregue no aparelho do contato
read	Lida pelo contato
failed	Falha reportada pelo WhatsApp, consulte error_message

O status evolui conforme o WhatsApp nos envia as confirmações, portanto é normal que uma consulta feita imediatamente após o callback retorne pending ou sent. Recomenda-se consultar novamente após alguns segundos.

5. Limitações

• A URL de callback vale apenas para a execução do fluxo disparada por aquele webhook. Se o fluxo enviar outro template mais tarde, por exemplo após uma resposta do contato, esse envio não gera callback.

• Somente mensagens do tipo template enviadas pelo fluxo acionado geram callback.

• O callback continua sem exigir chave de API, ele é uma configuração do webhook de cliente, não uma chamada à API. A chave é necessária apenas na consulta de status (seção 3).

• A consulta só encontra mensagens da sua própria conta.