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 e Enviar mídia.

{
  "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 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 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 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 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 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.