Skip to main content

​
Instância

Uma instância é um número de WhatsApp conectado como aparelho vinculado (o mesmo mecanismo do WhatsApp Web). Ela tem um instance_id, um token e um ciclo de vida: O celular não precisa ficar online o tempo todo: a sessão é multi-dispositivo. Ele precisa, porém, abrir o WhatsApp de vez em quando (o WhatsApp desconecta aparelhos vinculados após ~14 dias sem o celular).

​
Envio assíncrono e fila

Todo POST /send-* responde na hora com { id, message_id, wabox_id, status: "queued" } e coloca a mensagem na fila da instância. A fila:
  • aplica um intervalo aleatório entre mensagens (1 a 3 s por padrão) — o principal mecanismo anti-ban;
  • segura as mensagens enquanto a instância está desconectada e as envia ao reconectar (desligável com disable_enqueue_when_disconnected);
  • comporta até 1.000 mensagens por instância (409 queue_full acima disso).
O resultado de cada envio chega no webhook delivery, e os recibos (entregue, lida) no message_status. Detalhes em Fila e reenvio. Algumas ações não passam pela fila porque só fazem sentido agora: read-message, send-presence e tudo que é consulta ou administração (contatos, grupos, perfil…). Elas exigem instância conectada e respondem 409 instance_not_connected caso contrário.

​
Webhooks

O Wabox faz POST na URL que você configurar, um tipo de evento por URL: Cada entrega vem assinada (X-Wabox-Signature), tem event_id único e é reenviada se você não responder 2xx. Veja Visão geral dos webhooks.

​
Identificadores

Só dígitos, com DDI e DDD: 5511988887777. O mesmo campo aceita outros tipos de chat:
Ids de mensagem do WhatsApp são gerados pelo remetente. O Wabox gera o id no momento em que aceita o envio, devolve na resposta e manda o aparelho usar exatamente esse id. Por isso o message_id da resposta é o mesmo que aparece depois em delivery, message_status e nas respostas do contato (reference_message_id).id na resposta é um alias de message_id (facilita mapear em ferramentas no-code).
Id da mensagem na fila do Wabox (wbx_...). Use para remover uma mensagem da fila (DELETE /queue/{wabox_id}) e para casar o webhook delivery com a chamada original.
ULID único por evento. Entregas podem repetir (reenvio após timeout, por exemplo); guarde os event_id já processados.
O WhatsApp está migrando para LIDs (123456789012345@lid), identificadores que não expõem o número. Em alguns chats (especialmente grupos e contatos que ativaram o número oculto) você pode receber chat_lid/sender_lid/participant_lid e, em casos raros, um phone no formato xxx@lid sem o número real. Guarde o LID junto com o número: os endpoints aceitam xxx@lid em phone. Mais em Identificadores.

​
Workspace, instâncias e segurança

Uma conta (workspace) pode ter várias instâncias e vários usuários. Duas proteções valem para todas as instâncias do workspace: o header Client-Token e a allowlist de IPs.