> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ciclo de Vida das Mensagens

> Entenda os status e timestamps que acompanham cada mensagem

## Status de uma mensagem

Cada mensagem enviada pela Zapster passa por um ciclo de vida com status bem definidos. A tabela abaixo mostra todos os status possíveis:

| Status      | Descrição                               | Quando acontece                        |
| ----------- | --------------------------------------- | -------------------------------------- |
| `pending`   | Mensagem imediata sendo processada      | Ao enviar sem `send_at`                |
| `scheduled` | Agendada, aguardando o horário de envio | Ao enviar com `send_at`                |
| `sent`      | Enviada com sucesso ao WhatsApp         | Envio confirmado pela instância        |
| `failed`    | Falha no envio                          | Após 3 tentativas sem sucesso          |
| `canceled`  | Cancelada pelo usuário                  | Ao chamar `DELETE /v1/wa/messages/:id` |

Quando uma mensagem chega em `sent`, `failed` ou `canceled`, o status é final. Não muda mais.

## Timestamps

Além do status, cada mensagem carrega timestamps que indicam o que aconteceu e quando. Nem todos são preenchidos em todas as mensagens — depende do tipo de envio e do que aconteceu depois.

| Campo          | Preenchido quando              | Observação                                         |
| -------------- | ------------------------------ | -------------------------------------------------- |
| `created_at`   | A mensagem é criada            | Sempre preenchido                                  |
| `send_at`      | Definido pelo usuário          | Só existe em mensagens agendadas                   |
| `sent_at`      | Mensagem enviada com sucesso   | Preenchido quando o WhatsApp aceita o envio        |
| `delivered_at` | Entrega confirmada no aparelho | Quando a mensagem chega no celular do destinatário |
| `read_at`      | Destinatário leu a mensagem    | Quando o destinatário abre a conversa              |
| `canceled_at`  | Mensagem cancelada             | Quando o usuário chama `DELETE` antes do envio     |

## Sobre entrega e leitura

Os campos `delivered_at` e `read_at` dependem de fatores que estão fora do controle da Zapster:

* Se o destinatário desativou a confirmação de leitura nas configurações do WhatsApp, `read_at` nunca vai ser preenchido
* Se o celular do destinatário está sem internet, `delivered_at` pode demorar até ele ficar online de novo
* Esses campos não alteram o status da mensagem. Uma vez que o status é `sent`, ele permanece `sent`. Entrega e leitura são informações extras, registradas apenas nos timestamps

Na prática, você pode usar `delivered_at` e `read_at` para montar relatórios de entrega e leitura, mas não conte com eles para fluxos críticos. Nem todo destinatário vai gerar esses eventos.

## Quando uma mensagem falha

Se o status de uma mensagem é `failed`, o campo `errors` traz uma lista com os detalhes do que deu errado. A estrutura do erro varia um pouco dependendo do tipo de instância.

Para **instâncias oficiais (WABA)**, o `errors` inclui o código de erro da Meta e um link direto para a documentação deles:

```json theme={null}
{
  "errors": [
    {
      "code": 131047,
      "title": "Re-engagement message",
      "details": "Mais de 24 horas se passaram desde a última resposta do destinatário.",
      "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
    }
  ]
}
```

Alguns erros comuns em instâncias WABA:

* **131047**: Janela de 24 horas expirada. O destinatário não respondeu nas últimas 24h e você tentou enviar uma mensagem que não é template.
* **132000**: Template não encontrado. Verifique se o nome e o idioma do template estão corretos.
* **131026**: Número não está no WhatsApp ou é inválido.

Para **instâncias não oficiais (QR code)**, os erros mais comuns são:

* Instância offline (o celular perdeu conexão ou a sessão expirou)
* Número bloqueado ou inexistente no WhatsApp
* Limite de envio atingido pelo WhatsApp

Em todos os casos, o campo `errors` traz informações suficientes para você entender o que aconteceu e decidir se vale tentar novamente.