> For the complete documentation index, see [llms.txt](https://ajuda.livechat360.com.br/crm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.livechat360.com.br/crm/api-docs/status-de-entrega-de-mensagens.md). # Status de entrega de mensagens 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 ``` ```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 ``` ```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**](https://app.livechat360.com.br/dashboard/api); * o escopo **`messages`** com a operação **`read`** habilitado nessa chave. ```bash curl -H "Authorization: Bearer $KEY" \ "https://app-api.atendeserver.com.br/v1/messages/wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjhGMTk0RUY3NUYzODY5RDU3AA==" ``` Resposta `200 OK`: ```json { "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 `" - "` | | `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**.