integração · visão completa
Integração WhatsApp para o seu SaaS, do primeiro envio à fila de eventos
Uma integração WhatsApp que o seu time monta em dias: REST para enviar, webhook ou RabbitMQ para receber, SDK Node, n8n, MCP para agentes e mídia salva no seu bucket. Tudo por conexão, com o sessionId como chave do tenant.
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
Um contrato para enviar
REST com OpenAPI 3 e header Authorization. Funciona em qualquer linguagem; em Node, o d-api-sdk já vem tipado.
Dois caminhos para receber
Webhook por sessão com até 7 tentativas e backoff exponencial, ou eventos publicados no RabbitMQ do seu time.
Envio que não trava o request
Com async: true a API responde na hora com um commandId e avisa o resultado pelo webhook command.result.
Sem código quando faz sentido
Community node do n8n, bridge com o Datacrazy e servidor MCP para agentes de IA, sobre as mesmas conexões.
Integração WhatsApp, para um SaaS, é a soma de quatro decisões: como o seu backend envia, como ele fica sabendo do que aconteceu, como o seu cliente conecta o número dele e onde ficam os arquivos que trafegam na conversa. Cada decisão tem uma resposta simples e uma resposta que aguenta produção com centenas de clientes. Esta página mostra as duas, peça por peça, e aponta para o guia detalhado de cada uma.
O exemplo que atravessa o texto é um SaaS de agendamento para clínicas. Cada clínica conecta o próprio número, recebe confirmações de consulta pelo WhatsApp e responde pacientes de dentro do sistema. Troque “clínica” pelo seu segmento e o desenho continua o mesmo.
As peças de uma integração de WhatsApp
Antes do código, vale enxergar o todo. A D-API organiza tudo em torno da sessão: uma sessão é um número conectado, identificado por um sessionId que você escolhe. Todo envio informa o sessionId e todo evento devolve o sessionId.
| Peça | O que resolve | Quando usar |
|---|---|---|
| API REST | Criar sessões, enviar mensagens, consultar chats e contatos | Sempre |
SDK Node d-api-sdk |
Os mesmos endpoints com tipos TypeScript | Backend em Node |
| Webhook por sessão | Mensagens, status, conexão, grupos, chamadas | Ponto de partida para receber |
| Fila RabbitMQ por sessão | Os mesmos eventos no broker do seu time | Volume alto ou histórico completo |
| Comandos assíncronos | Envio enfileirado com resultado por webhook | Mídia pesada, lotes, campanhas |
| Integração S3/MinIO | Mídia recebida gravada no seu bucket | Retenção e controle dos arquivos |
| n8n, Datacrazy e MCP | Fluxos sem código, CRM pronto, agentes de IA | Operações e times não técnicos |
Enviar: API REST em qualquer linguagem
O lado de envio é o mais direto. A base é https://api.d-api.cloud, a autenticação vai no header Authorization com a sua API key e o contrato está publicado em OpenAPI 3. Primeiro você cria a sessão da clínica, já apontando 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": "clinica-sorriso",
"type": "unofficial",
"webhookUrl": "https://seu-saas.com/hooks/whatsapp/TOKEN"
}'
Com o número conectado, a confirmação da consulta é uma chamada:
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": "clinica-sorriso",
"to": "5511999999999",
"text": "Olá, Ana. Sua consulta é amanhã às 14h. Responda 1 para confirmar."
}'
Imagem, áudio, vídeo, documento, figurinha, localização, contato, enquete, reação e álbum têm rotas próprias em /api/v1/messages/send/*, com a mesma estrutura. Em Node, o SDK oficial para Node.js expõe tudo isso como métodos tipados, com timeout configurável e erro com o status HTTP. Em Python e PHP, um cliente HTTP comum resolve, e os guias desses dois casos estão listados no fim da página.
Receber: webhooks por sessão
Enviar sem receber deixa o produto pela metade. Quando a paciente responde “1”, o seu sistema precisa saber em segundos para marcar a consulta como confirmada. É o papel do webhook.
Cada sessão tem a própria configuração. No modo single, todos os eventos habilitados vão para uma URL. No modo per_event, cada evento tem a sua, o que permite separar o tráfego de mensagens do tráfego operacional. Todo evento chega no mesmo envelope, com event, sessionId, data, timestamp e traceId, então o seu parser é um só.
A entrega tem timeout de 30 segundos por tentativa e até 7 tentativas com backoff exponencial. Respostas 404 ou 410 encerram as tentativas para aquela URL, e há um circuit breaker por URL. A consequência prática: responda 2xx rápido, processe numa fila interna e trate o mesmo evento chegando duas vezes. O catálogo de eventos de webhook mostra cada evento e o payload que ele traz, de messages.received a connection.status.
Fila RabbitMQ quando o volume pede
Quando o seu time já opera um broker, receber direto numa fila RabbitMQ tira o endpoint HTTP do caminho e dá controle de prefetch, ack e reprocessamento. A configuração também é por sessão: você informa host, porta, usuário, senha, exchange e o mapa de eventos, e a D-API publica nesse exchange o mesmo envelope do webhook.
Há um motivo além do volume. Durante a sincronização de histórico, os eventos history.message.upsert e history.message.received são suprimidos no webhook e chegam só pelo RabbitMQ. Se o seu produto importa as conversas antigas da clínica ao conectar, a fila é o caminho completo. O guia de integração com RabbitMQ mostra a configuração e o consumidor.
Comandos assíncronos para não segurar o request
Por padrão, a API responde depois que o WhatsApp executa o comando. Para um texto, isso é rápido. Para um PDF de 10 MB ou um lote de 300 lembretes, o request fica aberto tempo demais.
Com async: true no corpo, a API enfileira o comando e responde na hora com um commandId e status: "queued". O resultado chega depois no webhook de conta command.result, com success dizendo se deu certo e o messageId em caso de envio. Somando sequential: true, os envios para o mesmo destinatário saem na ordem em que chegaram na API. O guia de comandos assíncronos cobre o fluxo, a assinatura HMAC desse webhook e os limites.
Mídia no seu bucket S3 ou MinIO
Paciente manda foto de exame, receita em PDF, áudio explicando o sintoma. Por padrão, a mídia recebida é armazenada pela D-API e o webhook traz a media_url pronta. Se a clínica ou o seu contrato exige que os arquivos fiquem num bucket seu, a integração S3 do painel grava a mídia recebida em qualquer storage compatível com S3, inclusive MinIO. A conexão é testada antes de salvar, e o guia de mídia do WhatsApp no S3 detalha os campos e o caminho dos arquivos.
Sem código: n8n e Datacrazy
Nem toda integração precisa passar pelo seu backend. O community node n8n-nodes-d-api coloca sessões, mensagens, chats e contatos como ações dentro de um workflow, e o nó de webhook do próprio n8n recebe os eventos. É o caminho de quem automatiza para clientes ou quer prototipar um fluxo antes de codificar. O guia de integração com n8n mostra a instalação e um fluxo completo.
Para operações comerciais que trabalham no Datacrazy, existe uma bridge dedicada: o CRM fala com a D-API por um conjunto de rotas próprio, com QR code, envio de texto, áudio, mídia e lista, e sincronização de mensagens por intervalo.
Agentes de IA com MCP
Se o seu produto tem um agente de IA, ele pode usar o WhatsApp como ferramenta. O servidor MCP da D-API responde em https://api.d-api.cloud/mcp, autentica pela mesma API key e gera as ferramentas a partir da OpenAPI. A ferramenta poll_messages entrega as mensagens que chegaram, e o parâmetro ?sessionId= na URL prende o conector à sessão de um único cliente. O passo a passo está em como conectar o seu agente de IA ao WhatsApp.
Conexão dentro do seu produto
O seu cliente não deveria precisar abrir o painel da D-API para conectar o número. O QR code sai de GET /api/v1/sessions/{sessionId}/qr em JSON, com a imagem PNG em base64, ou chega pelo evento connection.qrcode. O código de pareamento, para quem conecta pelo número de telefone, sai de GET /api/v1/sessions/{sessionId}/pair-code. Com isso, a tela de conexão fica com a sua marca, dentro do seu app, como mostra o guia de WhatsApp white label para SaaS.
Depois de conectado, o evento connection.status avisa cada mudança. O logout chega como connection.status com data.status: "logged_out", e é esse sinal que deve disparar o aviso “reconecte o seu WhatsApp” para a clínica.
Uma ordem de implementação que funciona
Times que integram WhatsApp pela primeira vez costumam travar tentando fazer tudo junto. Esta sequência entrega valor a cada etapa:
- Sessão e envio. Crie uma sessão de teste, conecte o seu próprio número e envie texto pela API. Valida autenticação e formato de número.
- Webhook mínimo. Um endpoint que confere um token no path, registra o
traceId, publica numa fila interna e responde 200. - Tela de conexão. QR code ou código de pareamento dentro do seu produto, com
connection.statusatualizando a tela. - Idempotência. Use o
data.idda mensagem como chave e ignore repetições. - Assíncrono e mídia. Mova envios pesados para
async: truee decida onde a mídia fica. - Escala. Avalie RabbitMQ, histórico e, se o produto pedir, o agente via MCP.
O custo acompanha a integração: a cobrança é por conexão ativa, sem tarifa por mensagem na API não oficial, e o preço por conexão cai com o volume. Os valores estão na tabela de preços do site.
Onde a integração costuma quebrar
Três pontos aparecem em quase todo onboarding. O primeiro é responder o webhook só depois de processar: com timeout de 30 segundos, uma chamada lenta ao banco vira retentativa e mensagem duplicada. O segundo é devolver 404 por erro de roteamento interno, que a D-API entende como URL inexistente e para de entregar. O terceiro é esquecer que mensagens enviadas pela sua integração chegam como messages.sent, enquanto messages.received com fromMe: true indica envio feito no celular do próprio número.
A referência completa de cada endpoint e evento está na documentação da D-API. Para o desenho de várias conexões por cliente, o artigo sobre API WhatsApp multi-tenant, listado abaixo, complementa esta página.
Time D-API. Atualizado em .
integração
Tudo sobre integração na D-API
- Agente de IA no WhatsApp com MCP: como conectar o seuConecte o seu agente de IA ao WhatsApp com o servidor MCP da D-API: URL, autenticação, um conector por cliente e leitura de mensagens com poll_messages.
- API WhatsApp Node.js com SDK TypeScript oficialAPI WhatsApp Node.js com o d-api-sdk: sessões, envio de mensagens, webhooks, mídia e ligações com tipos TypeScript, para o backend do seu SaaS.
- API WhatsApp PHP com curl ou Guzzle, direto na RESTAPI WhatsApp PHP sem SDK: conecte o número do cliente, envie mensagens e receba webhooks com curl nativo ou Guzzle, nos endpoints REST da D-API.
- API WhatsApp Python: REST com requests ou httpxAPI WhatsApp Python sem SDK: crie sessões, envie mensagens e receba webhooks com requests ou httpx, usando os endpoints REST reais da D-API.
- Comandos assíncronos na API de WhatsApp: envio em filaComandos assíncronos na API de WhatsApp: envie com async true, receba o commandId na hora e o resultado no webhook command.result, com ordem por contato.
- Eventos de webhook do WhatsApp: catálogo com payloadsEventos de webhook do WhatsApp na D-API: mensagens, status, conexão, chats, grupos, etiquetas, chamadas e histórico, com os campos de cada payload.
- Integração WhatsApp com CRM: conversa no card do leadIntegração WhatsApp com CRM para SaaS: conversas na timeline do lead, etiquetas sincronizadas com o funil e histórico importado quando o cliente conecta.
- Integração WhatsApp com ERP: boleto, nota e pedidoIntegração WhatsApp com ERP: envie boleto, nota fiscal e status de pedido em lote, com o resultado por webhook e a resposta do cliente ligada ao documento.
- Integração WhatsApp Datacrazy com a bridge da D-APIIntegração WhatsApp Datacrazy pela bridge dedicada da D-API: conexão por QR, envio de texto, áudio e mídia, histórico sincronizado e DDI +55 automático.
- Integração WhatsApp n8n com o community node da D-APIIntegração WhatsApp n8n com o node n8n-nodes-d-api: envie texto e mídia, consulte chats e receba eventos no nó Webhook, em n8n cloud ou self-hosted.
- Salvar mídia do WhatsApp no S3 ou MinIO do seu SaaSSalve a mídia do WhatsApp no S3 ou MinIO: fotos, áudios e documentos recebidos vão para o bucket da sua conta, e o webhook já traz a URL do arquivo.
- WhatsApp RabbitMQ: eventos da API no broker do seu SaaSWhatsApp RabbitMQ para SaaS: mensagens, status e histórico publicados no exchange do seu broker, por sessão, com o mesmo envelope do webhook.
- WhatsApp white label para SaaS: conexão com a sua marcaWhatsApp white label para SaaS: o seu cliente conecta o número por QR code ou código de pareamento dentro do seu produto, sem ver o painel da D-API.
Perguntas frequentes
Preciso usar o SDK para fazer a integração WhatsApp?
Não. O SDK d-api-sdk é opcional e cobre Node.js e TypeScript. A API REST é a mesma que ele chama por baixo, então Python, PHP, Go, Java ou qualquer outra linguagem com cliente HTTP integram do mesmo jeito.
A integração muda se o meu cliente quiser a API Oficial da Meta?
Muito pouco. A conexão oficial usa o mesmo sessionId nas rotas de envio e, com webhookMode normalized, entrega os eventos no mesmo formato da não oficial. O que muda é a regra da janela de 24 horas e o uso de templates.
Quanto tempo leva para ter a primeira mensagem saindo do meu produto?
Criar a sessão, ler o QR code e chamar o envio de texto cabe numa tarde. O trabalho maior vem depois: tela de conexão para o seu cliente, handler de eventos idempotente e tratamento de desconexão.
Consigo testar a integração antes de contratar?
Sim. SaaS liberado pelo time testa por 14 dias, com um grupo de onboarding em que o time técnico da D-API acompanha a implementação. No cadastro direto pelo painel, o teste é de 3 dias.
Como separo os dados de cada cliente do meu SaaS?
Crie uma sessão por número de cliente e guarde o sessionId ligado ao tenant no seu banco. Todo evento de webhook ou de fila traz o sessionId, que leva a mensagem ao tenant certo.