integração · envio em fila
Comandos assíncronos na API de WhatsApp: o request volta na hora, o resultado vem depois
Com comandos assíncronos na API de WhatsApp, o seu SaaS envia mídia pesada e lotes sem segurar o request: a D-API enfileira, responde com um commandId e avisa sucesso ou falha de cada comando no webhook command.result.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Resposta imediata
async: true no corpo e a API responde 200 com commandId e status queued antes de executar o comando.
Um resultado por comando
O webhook command.result chega uma vez por comando, com success, o retorno da rota e o motivo em caso de falha.
Ordem por destinatário
sequential: true faz os envios para o mesmo contato saírem na ordem de chegada, com até 100 pendentes.
Assinatura HMAC
Com secret configurado, cada entrega vem com X-DAPI-Signature, um HMAC-SHA256 do corpo bruto.
Comandos assíncronos na API de WhatsApp resolvem um problema que todo SaaS encontra quando o volume cresce: o request que fica pendurado esperando o WhatsApp. No modo padrão, a API só responde depois que o comando executa. Para um texto curto, ninguém percebe. Para um vídeo de 40 MB, um álbum de fotos ou os 500 lembretes que a sua plataforma dispara às 8h, o seu worker fica preso, o pool de conexões HTTP enche e um timeout do seu lado vira dúvida sobre se a mensagem saiu ou não.
Com async: true, a D-API inverte o fluxo. Ela enfileira o comando, responde na hora com um identificador e executa em segundo plano. O resultado chega depois, por webhook. Esta página mostra o ciclo completo, com o exemplo de uma plataforma de edtech que envia a aula gravada e o material em PDF para cada aluno.
Envio em fila: como o modo assíncrono funciona
O fluxo tem três passos:
- Envie o comando com
async: true. O campo vai no corpo JSON ou, nas rotasGET, na query string. Ele aceita booleanotrueou as strings"true"e"1". - Guarde o
commandIdda resposta. A API responde200antes de executar. - Receba o resultado no webhook
command.result, que chega uma única vez por comando, com o mesmocommandId.
curl -X POST https://api.d-api.cloud/api/v1/messages/send/video \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "escola-codigo-livre",
"to": "5511999999999",
"video": "https://cdn.seu-saas.com/aulas/modulo-3.mp4",
"caption": "Aula 3 do curso de Python",
"async": true
}'
A resposta do enfileiramento:
{
"commandId": "9f1c8f2e-4b7a-4f10-9c3d-2e1a8b5d7c40",
"success": true,
"status": "queued",
"message": "Command queued",
"timestamp": "2026-11-15T11:00:21.902Z",
"sessionId": "escola-codigo-livre",
"to": "5511999999999",
"messageType": "video"
}
Leia esse success: true com cuidado: ele diz que o comando entrou na fila, e ainda não diz se o vídeo foi enviado. Se a API não conseguir enfileirar, ela responde com erro e o comando não é executado, o que torna seguro tentar de novo.
O modo assíncrono vale para as rotas de envio de mensagem (texto, imagem, vídeo, áudio, documento, figurinha, localização, contato, enquete, reação e álbum) e também para grupos, contatos e chats, etiquetas, catálogo, canais, histórico e download de mídia. Sessões da API Oficial ignoram o async e respondem sempre de forma síncrona.
O webhook command.result
O resultado de todos os comandos assíncronos da conta vai para uma única URL, configurada uma vez. É um webhook de conta, separado dos webhooks de eventos de cada sessão. A configuração fica no painel, em Integrações, Webhook de Comandos, ou pela API:
curl -X PUT https://api.d-api.cloud/api/v1/account/webhooks/command \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://app.seu-saas.com/hooks/dapi-comandos",
"secret": "um-segredo-forte",
"events": ["command.result"],
"enabled": true
}'
O enabled começa em false, então sem esse passo nada é enviado. O secret omitido mantém o atual, null remove e o valor nunca é devolvido: GET /api/v1/account/webhooks mostra hasSecret no lugar dele.
O evento chega com event: "command.result", channel: "command" e, em data, o commandId, o sessionId, o commandType (como send_text ou send_image), success, data com o retorno que a rota daria no modo síncrono (o messageId, em envios) e error com o motivo quando success é false. Os headers incluem X-DAPI-Webhook-Channel: command e, com secret, X-DAPI-Signature.
app.post('/hooks/dapi-comandos', express.raw({ type: 'application/json' }), async (req, res) => {
const signature = req.get('X-DAPI-Signature');
const expected = crypto.createHmac('sha256', process.env.DAPI_CMD_SECRET!).update(req.body).digest('hex');
const valid = !!signature && signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
if (!valid) return res.sendStatus(401);
res.sendStatus(200);
const { data } = JSON.parse(req.body.toString());
await envios.registrarResultado(data.commandId, {
ok: data.success,
messageId: data.data?.messageId ?? null,
erro: data.error,
});
});
O HMAC é calculado sobre o corpo bruto, por isso a rota usa express.raw. A mesma validação em Python, com hmac.compare_digest, está no guia de API WhatsApp Python. Use success para decidir o fluxo e trate error como texto de log: ele vem do WhatsApp ou da camada de execução e pode mudar.
Garantias que o seu código pode assumir
Saber o que a D-API garante define o que o seu código precisa fazer:
- Um resultado por comando. Cada comando gera exatamente um
command.result, comsuccess: trueoufalse, inclusive quando estoura o tempo limite. - Nunca reexecutado. Comando que falhou não é repetido pela D-API. Reenviar depende do seu código, depois de ler o
error. - Entrega com retentativa. O endpoint precisa responder
2xxem até 30 segundos. Fora disso, a entrega é repetida com backoff exponencial, de 15 e depois 30 segundos, em até 3 tentativas no total. Respostas404ou410encerram as tentativas, e um endpoint que falha repetidamente tem a entrega suspensa por um tempo. - Duplicidade possível. Por causa da retentativa, o mesmo
command.resultpode chegar duas vezes. OcommandIdé a chave de idempotência. - Ordem livre. Comandos rodam em paralelo e podem terminar em ordem diferente da de envio. Não dependa da ordem de chegada dos webhooks.
Para a plataforma de edtech, isso vira uma regra simples: grave o commandId junto do envio no momento da chamada e atualize o registro quando o resultado chegar, ignorando o que já foi atualizado.
Consultar um comando pelo commandId
GET /api/v1/commands/{commandId} mostra o estado atual e traz em result o mesmo payload do webhook, preenchido quando o comando termina. É útil para depuração e para reconciliar um caso pontual.
status |
Significado |
|---|---|
queued |
Na fila, ainda não começou |
processing |
Executando agora |
completed |
Executou; veja result.success |
failed |
O worker falhou antes de concluir; o motivo vem em error |
Um comando que rodou e falhou, por número inválido ou sessão desconectada, fica completed com result.success: false. O resultado fica consultável por cerca de uma hora após a execução, ou 24 horas se o worker falhar. Depois disso, a consulta responde 404, igual a um commandId inexistente ou de outra conta. Para produção, o webhook é o canal certo, e a consulta é complemento.
Ordem garantida com sequential
Comandos em paralelo têm um efeito colateral: o PDF leve pode chegar antes do vídeo pesado enviado um segundo antes. Para envios de mensagem, sequential: true junto de async: true faz os envios para o mesmo destinatário saírem um de cada vez, na ordem de chegada na API. A ordem é por sessão e destinatário, e envios para outros alunos continuam em paralelo.
O próximo envio começa quando o anterior termina, com sucesso ou falha, e uma falha não interrompe a sequência. O sequential vale para texto, imagem, vídeo, áudio, documento, figurinha, localização e contato. Dois limites entram no desenho:
- A ordem é a de chegada. Requests disparados em paralelo pelo seu sistema não têm ordem definida. Envie em série para o mesmo aluno; como a resposta é imediata, isso continua rápido.
- Até 100 pendentes por destinatário. Acima disso, a API responde
429comRetry-Afterentre 1 e 60 segundos, e o envio não entra na fila.
Erros comuns
| Sintoma | Causa provável |
|---|---|
status: "queued", mas nenhum webhook chega |
Webhook de comandos não configurado, desativado ou com events sem command.result |
command.result com success: false |
O comando executou e falhou; veja error |
async: true sem efeito |
Sessão da API Oficial, sempre síncrona |
Consulta pelo commandId responde 404 |
Resultado expirado, commandId inexistente ou de outra conta |
O mesmo commandId chegou duas vezes |
Retentativa de entrega; deduplique |
Para um caso real de lote com ordem, documento e reconciliação, a página de integração WhatsApp com ERP aplica tudo isso a boletos e notas fiscais. Os eventos de sessão, que seguem por outro canal, estão no catálogo de eventos de webhook.
A referência completa, com a lista de rotas compatíveis, está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
O comando assíncrono funciona na API Oficial?
Não. Sessões da API Oficial ignoram o async e respondem sempre de forma síncrona, porque o envio passa direto pela Meta, sem fila.
Se o comando falhar, a D-API tenta de novo?
Não. O comando nunca é reexecutado, porque repetir um envio pode duplicar a mensagem. O command.result chega com success false e o motivo em error, e o reenvio fica a seu critério.
E se eu não configurar o webhook de comandos?
O comando executa normalmente, mas o resultado não é enviado a lugar nenhum. Ele fica disponível só na consulta por GET /api/v1/commands/{commandId}, por cerca de uma hora.
Posso receber o command.result mais de uma vez?
Pode. A entrega tem retentativa, então um endpoint que processa e responde depois de 30 segundos recebe o mesmo evento de novo. Use o commandId como chave de idempotência.
Quais rotas aceitam async além das de mensagem?
Grupos, contatos e chats, etiquetas, catálogo, canais, histórico e download de mídia. A lista completa de rotas compatíveis está na documentação de comandos assíncronos.