Como funciona a API de WhatsApp, da conta ao webhook

O fluxo inteiro em uma lista

Antes de entrar no detalhe, vale ver o caminho completo. Cada item depende do anterior, e é nessa ordem que o time de desenvolvimento vai implementar:

1. Conta e API Key. Você se cadastra no painel e copia a chave. Ela vai no header Authorization de toda requisição, sem o prefixo Bearer.
2. Criar a sessão. Uma sessão é uma conexão com um número. Você escolhe o sessionId e, opcionalmente, já informa a URL do webhook.
3. Ler o QR code. A API devolve o QR, o dono do número escaneia pelo celular e a sessão passa a ficar conectada.
4. Enviar. Texto, mídia, listas e grupos são chamadas POST com o sessionId e o número de destino.
5. Receber por webhook. Mensagens que chegam, confirmações de leitura e mudanças de estado viram requisições para a sua URL.
6. Monitorar a conexão. Seu sistema precisa saber quando um número caiu, para avisar o cliente antes que ele perceba sozinho.

Esse é o desenho de qualquer API de WhatsApp que conecta por QR. Nos exemplos, a base é https://api.d-api.cloud e todos os caminhos começam com /api/v1.

Etapas 1 e 2: autenticar e criar a sessão

Com a chave copiada do painel, a primeira chamada cria a conexão. O campo type define se ela é não oficial (unofficial, conectada por QR) ou oficial (cloud_api). Aqui usamos a não oficial e já apontamos o webhook:

curl -X POST https://api.d-api.cloud/api/v1/sessions \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "cliente-42",
    "type": "unofficial",
    "webhookUrl": "https://seu-app.com/webhooks/whatsapp"
  }'

Escolha um sessionId que já faça sentido no seu banco, como o ID do cliente ou da unidade. Isso evita uma tabela de tradução depois: quando o webhook chegar, o próprio identificador diz de quem é o evento.

Etapa 3: conectar o número pelo QR

A sessão nasce aguardando pareamento. Para exibir o QR na sua tela, busque a imagem pronta com ?image=1, que devolve um PNG:

curl "https://api.d-api.cloud/api/v1/sessions/cliente-42/qr?image=1" \
  -H "Authorization: SUA_API_KEY" \
  --output qr.png

Sem o parâmetro, a resposta vem em JSON, com o texto do QR, a versão em base64 e o horário da última atualização. O QR expira em poucos segundos e é renovado sozinho, então a interface do seu produto deve buscar de novo enquanto o status for connecting. Quem prefere não usar câmera pode parear por código numérico; os detalhes estão em conectar pela API com QR code.

Etapa 4: enviar a primeira mensagem

Com o número conectado, enviar é uma requisição com três campos obrigatórios: sessionId, to e text. O destino vai no formato internacional, sem o sinal de mais:

curl -X POST https://api.d-api.cloud/api/v1/messages/send/text \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "cliente-42",
    "to": "5511999999999",
    "text": "Sua consulta de amanhã às 14h está confirmada."
  }'

Imagem, áudio, vídeo e documento seguem o mesmo padrão em rotas próprias, trocando text pelo campo do arquivo. Se o seu sistema dispara muitos envios de uma vez, o campo opcional async devolve um commandId na hora, e o resultado pode ser consultado depois, sem segurar a requisição.

Em Node, o mesmo trecho fica mais curto com o SDK oficial, que tem sessions.create, sessions.getQRCode e messages.sendText. Veja a página do SDK de Node.js.

Etapa 5: receber eventos por webhook

Tudo o que acontece no número chega à URL configurada como um POST em JSON. O envelope é sempre o mesmo: nome do evento, sessionId, os dados e um traceId para rastrear o caminho da mensagem nos seus logs.

{
  "event": "messages.received",
  "sessionId": "cliente-42",
  "data": {
    "id": "3EB0...",
    "type": "text",
    "fromMe": false,
    "is_group": false,
    "from_name": "Maria"
  },
  "timestamp": "2026-01-24T22:51:32.601Z",
  "traceId": "c17dee..."
}

Três cuidados no seu endpoint: responda rápido com status 200 e processe depois, numa fila sua; trate o mesmo evento chegando duas vezes sem duplicar efeito; e proteja a URL, já que o webhook de WhatsApp não vem assinado. A documentação recomenda URL secreta e checagem do sessionId. Se o seu servidor falhar, a D-API tenta de novo até sete vezes, com intervalo crescente. Os eventos disponíveis e a configuração por evento estão em webhook da API de WhatsApp.

Etapa 6: saber quando a conexão cai

Um número pode desconectar porque o dono removeu o aparelho vinculado, porque o WhatsApp encerrou a sessão ou por instabilidade. Há duas formas de acompanhar:

• Pelo evento connection.status: o campo data.status chega como connected, disconnected ou logged_out. É o jeito recomendado, porque o aviso chega no momento da mudança.
• Consultando a sessão: GET /api/v1/sessions/cliente-42 retorna os dados da sessão, incluindo o status. Serve para uma tela de diagnóstico ou para conferir o estado depois de um deploy.

A diferença entre os dois estados de queda importa: disconnected costuma se resolver com reconexão, que a infraestrutura tenta sozinha, enquanto logged_out significa que o número foi desvinculado e alguém precisa ler um QR novo. Quando esse segundo caso acontece, o ideal é o seu produto mostrar o aviso na tela do cliente, e não ele descobrir porque as mensagens pararam.

Onde a implementação costuma travar

As chamadas em si são simples. O trabalho de verdade aparece na borda do seu sistema: guardar a relação entre sessão e cliente, montar a tela de pareamento, processar webhook sem perder evento e decidir o que fazer quando um número cai. Quem precisa de uma conexão por cliente, como um SaaS, gasta a maior parte do esforço aí, e por isso vale olhar a API de WhatsApp para SaaS antes de desenhar a arquitetura.