Skip to main content
Cada instância tem uma fila de saída. Todo POST /send-* (e reações, encaminhamentos, enquetes, fixar, apagar) entra nela e sai na ordem, respeitando o intervalo anti-ban.

​
Ciclo de uma mensagem

  • A resposta é imediata, com wabox_id (id na fila) e message_id (id no WhatsApp, já definitivo).
  • O intervalo é aleatório entre delay_message_min_ms e delay_message_max_ms (padrão 1.000 a 3.000 ms) e conta do fim da mensagem anterior. delay_message na chamada substitui esse intervalo para aquela mensagem, e delay_typing acrescenta “digitando…” antes.
  • A fila envia uma mídia por vez por instância, e textos não esperam mídia.

​
Quando a instância está desconectada

Por padrão, a fila aceita e segura as mensagens. Ao reconectar (connected), elas saem na ordem, com o intervalo normal, e nada é disparado de uma vez. Se preferir falhar rápido, ligue disable_enqueue_when_disconnected em PUT /settings: os envios passam a responder 409 queue_disabled_while_disconnected enquanto o número estiver fora.

​
Validade das mensagens na fila

Uma mensagem que espera mais que queue_max_age_hours (padrão 12 h, de 1 a 168) sai da fila sem ser enviada, e você recebe um delivery com error_code: "queue_expired", mesmo com a instância ainda desconectada. Ao reconectar, o Wabox envia só o que ainda está dentro da validade.
Você também ajusta isso no painel, em Webhooks e configurações › Geral.
Mensagens presas na fila por muito tempo podem ficar obsoletas (“seu código expira em 5 minutos”). Para conteúdo sensível a tempo, use uma validade curta (queue_max_age_hours: 1), consulte GET /status antes de enviar ou ligue disable_enqueue_when_disconnected e trate o 409.

​
Inspecionar e limpar

GET /queue lista wabox_id, message_id, phone, type e o conteúdo, paginado. Mensagens já enviadas não aparecem, porque o Wabox não guarda o que já saiu. O histórico recente vem só do pareamento.

​
Capacidade

A fila comporta 1.000 mensagens por instância. Acima disso, POST /send-* responde 429 queue_full. Com o intervalo padrão, 1.000 mensagens levam cerca de 30 a 50 minutos para sair. Se você bate nesse teto, distribua os envios entre várias instâncias.

​
Reenvio e falhas

  • O Wabox tenta enviar cada mensagem enquanto o aparelho estiver conectado. Falhas definitivas (phone_not_on_whatsapp, media_invalid, message_not_found, not_allowed) viram delivery com error_code, e a mensagem sai da fila.
  • send_timeout significa que o aparelho não confirmou a tempo. A mensagem pode ter saído. Não reenvie às cegas: espere o message_status ou confira com o contato.
  • queue_expired significa que a mensagem passou de queue_max_age_hours esperando na fila e foi descartada sem envio. Reenviar é seguro (nada saiu).
  • Falhas transitórias entre a fila e o aparelho (engine reiniciando, instância caindo bem na hora) não viram delivery. A mensagem volta para a fila e o Wabox tenta de novo automaticamente (30 s, 1 min, 2 min… até 10 min entre tentativas, ou no próximo connected). Uma rotina a cada minuto recupera mensagens que ficaram presas “enviando” sem resposta (até 3 tentativas, depois delivery com send_failed).
  • Falhas definitivas não têm reenvio automático. Se você precisa garantir a entrega, implemente isso no seu lado: registre o wabox_id, espere o delivery e reenvie só as falhas que façam sentido repetir.

​
Mensagens referenciadas (responder, encaminhar, editar, votar)

reply_to_message_id, forward-message, edit_message_id, send-poll-vote e send-event-response precisam do conteúdo da mensagem original, que o WhatsApp não fornece sob demanda. O engine mantém um cache em memória (as últimas ~4.000 mensagens por instância, recebidas ou enviadas desde o último restart). Fora do cache, o resultado é delivery com message_not_found. Responder ou encaminhar mensagens recentes funciona. Mensagens de dias atrás ou anteriores a um restart do engine falham com message_not_found. Se a citação for opcional para você, trate esse erro reenviando sem reply_to_message_id.

​
Ordem entre instâncias

Cada instância tem a sua fila. Se várias instâncias enviam para o mesmo contato, não há ordenação entre elas.