Pular para o conteúdo
D-APITestar grátis

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:

  1. Envie o comando com async: true. O campo vai no corpo JSON ou, nas rotas GET, na query string. Ele aceita booleano true ou as strings "true" e "1".
  2. Guarde o commandId da resposta. A API responde 200 antes de executar.
  3. Receba o resultado no webhook command.result, que chega uma única vez por comando, com o mesmo commandId.
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, com success: true ou false, 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 2xx em até 30 segundos. Fora disso, a entrega é repetida com backoff exponencial, de 15 e depois 30 segundos, em até 3 tentativas no total. Respostas 404 ou 410 encerram 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.result pode chegar duas vezes. O commandId é 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 429 com Retry-After entre 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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.