# Filas de mensagem

Use `async: true` para aceitar rapidamente um envio direto e processá-lo pela fila da instância. A resposta confirma que a mensagem entrou na fila — não que chegou ao destinatário.

## Envio direto ou assíncrono?

| Fluxo | Quando usar | O que a resposta informa |
|---|---|---|
| Direto | Quando você precisa aguardar a tentativa de envio | Resultado daquela tentativa |
| `async: true` | Para absorver picos e não manter a requisição aberta durante o envio | Aceite na fila e posição aproximada |

O campo `async` está disponível nas operações de envio que o exibem no schema, como [Enviar texto](/endpoint/post/send~text) e [Enviar mídia](/endpoint/post/send~media).

```json
{
  "number": "5511999999999",
  "text": "Olá! Sua solicitação foi recebida.",
  "async": true,
  "track_source": "meu-sistema",
  "track_id": "pedido-123"
}
```

Uma resposta aceita contém `status: "Queued"`, `async: true`, os identificadores da mensagem e `queuePosition`. Preserve o campo `id`; a posição é uma fotografia do momento e não uma previsão de horário.

## Acompanhar a fila

Consulte [GET /message/async](/endpoint/get/message~async) para obter a situação geral da fila da instância.

| Status | Significado |
|---|---|
| `idle` | Não há mensagens pendentes |
| `queued` | Há mensagens aguardando processamento |
| `processing` | Uma mensagem está sendo processada agora |
| `waiting_connection` | A fila aguarda a sessão ficar pronta |
| `waiting_warmup` | A fila aguarda a preparação da sessão |
| `waiting_history` | A fila aguarda a preparação do histórico |
| `resetting` | A fila está temporariamente indisponível durante uma limpeza ou reinicialização |

Use `pending` para acompanhar o volume restante, `processingNow` para saber se há trabalho em andamento e `acceptingNewMessages` antes de adicionar novos envios. `sessionReady: false` explica por que uma fila pode permanecer pendente.

## Acompanhar uma mensagem

O estado geral da fila não substitui o acompanhamento individual. Busque a mensagem pelo `id` em [POST /message/find](/endpoint/post/message~find) ou acompanhe o evento `messages_update`.

| Estado | Significado |
|---|---|
| `Queued` | Aceita e aguardando processamento |
| `Sent` | Enviada pela sessão; ainda não significa entrega ou leitura |
| `Failed` | O envio terminou com falha |
| `Expired` | A mensagem não pôde ser enviada dentro da janela disponível |
| `Canceled` | A mensagem pendente foi cancelada pela limpeza da fila |

Antes de repetir um envio após timeout ou desconexão, consulte a mensagem pelo ID ou pelos campos de rastreamento. Reenviar sem essa conferência pode gerar duplicidade.

## Intervalo entre mensagens

[Configure o intervalo da fila](/endpoint/post/instance~updateDelaySettings) para controlar o tempo entre envios assíncronos. Essa configuração pertence à fila de mensagens diretas e não altera campanhas.

## Limpar a fila

[DELETE /message/async](/endpoint/delete/message~async) cancela todas as mensagens ainda pendentes da instância. Mensagens já enviadas não são desfeitas. Use a limpeza somente quando a intenção for cancelar todo o trabalho pendente.

## O que não entra nesta fila

- [Mensagem em massa](/docs/bulk-messaging) possui acompanhamento e controle próprios.
- Publicações em canais/newsletters não usam esta fila, mesmo que `async: true` seja informado.
- `Queued` não comprova entrega, leitura nem sucesso da regra de negócio do destinatário.