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

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:

  1. 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.
  2. Webhook mínimo. Um endpoint que confere um token no path, registra o traceId, publica numa fila interna e responde 200.
  3. Tela de conexão. QR code ou código de pareamento dentro do seu produto, com connection.status atualizando a tela.
  4. Idempotência. Use o data.id da mensagem como chave e ignore repetições.
  5. Assíncrono e mídia. Mova envios pesados para async: true e decida onde a mídia fica.
  6. 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

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.

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.