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

integração

API WhatsApp multi-tenant com uma conexão por cliente

Como modelar uma API WhatsApp multi-tenant no seu SaaS: uma conexão isolada por cliente, um único webhook e criação de sessões via API.

Time D-API. Atualizado em .8 min de leitura.

Uma API WhatsApp multi-tenant resolve o problema que todo SaaS encontra no segundo cliente: cada empresa quer o próprio número, o próprio histórico e nenhuma chance de ver a conversa do vizinho. O caminho que escala é simples de explicar. Cada cliente do seu SaaS ganha uma conexão isolada, identificada por um sessionId que você controla, e o seu backend fala com todas elas usando uma única chave e um único endpoint de eventos.

Este guia mostra como modelar isso na prática: a relação entre tenant e conexão, a criação de sessões pela API, o recebimento de eventos de todas as conexões num só lugar e o que muda quando o cliente prefere a API Oficial da Meta. Os exemplos usam endpoints reais da D-API, que hoje opera mais de 1.300 conexões ativas em 4 datacenters no Brasil com 99,9% de uptime garantido em contrato.

O objetivo é que você saia daqui com um desenho que funciona com 10 clientes e continua igual com 400.

O modelo mental: tenant tem conexões, conexão tem sessionId

O ganho para o SaaS é ter uma única regra de roteamento no código inteiro. Tudo o que entra e sai do WhatsApp carrega um identificador de sessão, e esse identificador aponta para exatamente um cliente seu.

Na D-API, uma conexão representa um número de WhatsApp conectado. Você escolhe o sessionId na criação, e ele aparece em praticamente todos os outros endpoints: envio, consulta, configuração de webhook, chamadas. A documentação recomenda um valor estável e único por número.

Uma modelagem que funciona bem:

  • tenants: os clientes do seu SaaS (o que você já tem).
  • whatsapp_connections: session_id (único), tenant_id, type (unofficial ou cloud_api), status, timestamps.

Com isso, um tenant pode ter várias conexões (vendas, suporte, financeiro) e cada conexão pertence a um tenant só. Use um padrão de sessionId que já ajude no debug, como acme-42-vendas, mas trate o seu banco como fonte da verdade e nunca extraia o tenant do texto do ID.

Por que uma conexão por cliente

Isolamento por conexão significa que a instabilidade, a reconexão ou o volume de um cliente não interferem no outro. Na D-API as conexões são isoladas e usam IPs dedicados, o que dá ao seu suporte uma resposta clara quando um cliente reclama: o problema está naquela conexão, com logs próprios em GET /api/v1/sessions/{sessionId}/logs. Num arranjo multi-tenant bem feito, o tenant é a fronteira de dados e a conexão é a fronteira operacional.

Criar a conexão do cliente pela API

O resultado que importa aqui é o onboarding sem intervenção do seu time: o cliente clica em “conectar WhatsApp” no seu produto e a conexão nasce na hora.

A criação é um POST /api/v1/sessions. Além de sessionId e type, o corpo aceita webhookUrl e um objeto metadata livre, onde você pode guardar o tenantId junto da sessão:

curl -X POST https://api.d-api.cloud/api/v1/sessions \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "acme-42-vendas",
    "type": "unofficial",
    "webhookUrl": "https://seu-saas.com/hooks/dapi/TOKEN_SECRETO",
    "metadata": { "tenantId": "acme-42" }
  }'

Na API não-oficial, o cliente conecta o número lendo um QR code. Você tem duas formas de exibir o código dentro do seu produto:

  1. Buscar em GET /api/v1/sessions/{sessionId}/qr. Sem o parâmetro ?image=1, a resposta vem em JSON, pronta para renderizar no seu front-end.
  2. Ouvir o evento connection.qrcode no webhook, que já traz o QR em texto (qr) e a imagem em base64 (qrImage).

Se o cliente preferir não escanear nada, crie a sessão com connectionMode: "pair" e pairPhone, e mostre o código de pareamento que chega em connection.paircode ou em GET /api/v1/sessions/{sessionId}/pair-code.

Depois de conectado, o envio usa o mesmo sessionId, sempre a partir do seu backend:

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": "acme-42-vendas", "to": "5511999999999", "text": "Seu pedido saiu para entrega." }'

Antes de enviar, o seu código deve confirmar que aquela sessão pertence ao tenant da requisição. A API key é sua e enxerga todas as conexões, então a autorização por tenant é responsabilidade do seu backend.

Um webhook para todas as conexões

Aqui o benefício é operacional: um endpoint, um deploy, um lugar para observar. Você não precisa de uma URL por cliente para saber de quem é cada evento.

Todo webhook da D-API chega com o mesmo envelope, e o sessionId está sempre no topo:

{
  "event": "messages.received",
  "sessionId": "acme-42-vendas",
  "data": { "...": "específico do evento" },
  "timestamp": "2026-01-24T22:51:32.601Z",
  "traceId": "c17dee440402792623e3ad6d925cb000"
}

O handler faz três coisas: valida a origem, resolve o tenant pelo sessionId e devolve 2xx rápido. A D-API espera até 30 segundos por resposta e retenta em caso de falha, então o processamento pesado deve ir para uma fila:

app.post("/hooks/dapi/:token", async (req, res) => {
  if (req.params.token !== process.env.DAPI_WEBHOOK_TOKEN) return res.sendStatus(401);

  const { event, sessionId, data, traceId } = req.body;
  const connection = await connections.findBySessionId(sessionId);
  if (!connection) return res.sendStatus(200); // sessão removida: confirma e ignora

  await queue.publish("whatsapp-events", {
    tenantId: connection.tenantId,
    event,
    sessionId,
    data,
    traceId,
  });
  res.sendStatus(200);
});

Dois detalhes desse código vêm direto da documentação. A D-API não assina os webhooks com HMAC, por isso a recomendação é usar uma URL com token secreto no path e conferir se o sessionId é esperado. E o traceId merece ir para o seu log estruturado junto com o tenantId, porque é o identificador que o suporte usa para rastrear um evento de ponta a ponta.

Se o volume crescer a ponto de você preferir consumir de uma fila em vez de receber HTTP, cada sessão também pode publicar num RabbitMQ seu. O artigo sobre webhooks e fila RabbitMQ detalha retentativas, timeout e quando escolher cada modelo.

Ciclo de vida da conexão por tenant

Clientes conectam, trocam de aparelho, cancelam o plano. Tratar esses momentos de forma automática evita ticket de suporte e cobrança de conexão que ninguém usa.

O evento connection.status informa cada mudança de estado em data.status: connected, disconnected ou logged_out. Um logout (por exemplo, quando o cliente remove o aparelho conectado) chega sempre como connection.status com status: "logged_out", nunca como evento separado. Atualize a coluna status da sua tabela a cada evento e avise o tenant quando for preciso reconectar.

Para as rotinas de gestão:

  • GET /api/v1/sessions lista as sessões com paginação, busca e filtros (como type=cloud_api), útil para reconciliar o seu banco com o estado real.
  • GET /api/v1/sessions/{sessionId}/connect reconecta uma sessão com restart.
  • DELETE /api/v1/sessions/{sessionId} remove a conexão quando o cliente sai.

Rode a reconciliação de forma paginada e periódica, sem depender de estado em memória. Assim o processo funciona igual com uma ou dez réplicas do seu backend.

Quando o cliente quer a API Oficial

Parte dos seus clientes vai pedir a API Oficial da Meta. A boa notícia para o seu SaaS é que o modelo de dados não muda: a conexão continua sendo uma linha na mesma tabela, com outro type.

O cliente conecta o número dele por um popup hospedado pela D-API, que roda o Embedded Signup da Meta. Você inicia o fluxo no front-end com uma publishable key, que só serve para onboarding e não envia mensagens nem lê dados:

import { DApiConnect } from "d-api-sdk/connect";

const connect = new DApiConnect({ publishableKey: "pk_live_…" });

const { connectionId } = await connect.start({
  webhookUrl: "https://seu-saas.com/hooks/dapi/TOKEN_SECRETO",
  webhookMode: "normalized",
  metadata: { tenantId: "acme-42" },
});

O connectionId retornado é o sessionId nas rotas normais de envio. Com webhookMode: "normalized", os eventos chegam no mesmo formato canônico da não-oficial, então o handler da seção anterior serve para os dois tipos sem nenhum if.

O metadata resolve um caso que pega muita gente no celular. Em navegador mobile, o popup abre como aba e o start() pode rejeitar mesmo com a conexão criada. O webhook session.created sempre chega no webhookUrl da conexão com data.metadata intacto, e é por ele que você liga a conexão ao tenant sem depender do retorno síncrono. O limite é de 512 bytes de JSON serializado, então guarde identificadores, nunca objetos de negócio inteiros.

O passo a passo completo, incluindo coexistência e os códigos de erro do onboarding, está na documentação da D-API.

Quem paga o quê

Na API Oficial, as tarifas de mensagem da Meta são cobradas na conta Meta (WABA) do seu cliente. A D-API cobra de você o mesmo preço por conexão da não-oficial. Isso deixa a sua precificação simples: você repassa a conexão como quiser e o custo de mensagens fica com quem envia. Os valores da Meta por categoria estão na tabela de preços da Meta.

Escala sem retrabalho

O desenho acima cresce de forma linear, e isso aparece em três pontos.

No código, nada depende do número de clientes. O handler de webhook é o mesmo para 10 ou 400 conexões, o envio é sempre sessionId mais destinatário e a reconciliação é paginada. O que cresce é o volume da sua fila, que você escala com mais workers.

No custo, o preço por conexão cai conforme o volume, o que favorece justamente o SaaS que está crescendo. Os valores por faixa estão na tabela de preços.

Na operação, cada conexão tem status, logs e eventos próprios. Quando um cliente abre chamado, o seu suporte filtra pelo sessionId e pelo traceId e chega à resposta sem misturar dados de outros tenants. E se a dúvida for de infraestrutura, o suporte da D-API é humano.

Se você ainda está decidindo se vale manter essa camada dentro de casa, o artigo sobre infraestrutura WhatsApp própria compara os dois caminhos. E para entender como as duas APIs convivem no mesmo código, veja API oficial e não oficial na mesma integração.

Por onde começar

Comece pela tabela whatsapp_connections e pelo endpoint de webhook único. Com os dois no lugar, criar a primeira sessão de teste leva poucos minutos: um POST /api/v1/sessions com o tenantId no metadata, o QR exibido no seu front-end e um messages.received chegando no handler.

Depois, adicione o tratamento de connection.status para avisar clientes desconectados e, quando o primeiro cliente pedir a API Oficial, plugue o DApiConnect usando o mesmo handler. A partir daí, cada novo cliente é só mais uma linha na tabela.

Veja também: Integração, API de WhatsApp.

Perguntas frequentes

Preciso de uma API key por cliente do meu SaaS?

Não. Você usa a sua API key secreta no backend e diferencia os clientes pelo sessionId de cada conexão. A chave nunca vai para o navegador.

Posso apontar todas as conexões para o mesmo webhook?

Pode. Todo evento chega com o sessionId no envelope, então um único endpoint recebe tudo e distribui para o tenant certo consultando o seu banco.

Como sei qual cliente conectou um número da API Oficial pelo celular?

Passe metadata com o seu tenantId no connect.start(). O webhook session.created devolve esse JSON intacto em data.metadata, mesmo quando o popup não consegue responder ao navegador.

A API Oficial e a não-oficial usam modelagens diferentes?

Não. Na API Oficial o connectionId é o sessionId nas rotas de envio e, no webhookMode normalized, os eventos chegam no mesmo formato da não-oficial. A tabela de conexões do seu SaaS serve para os dois tipos.

Quem paga as mensagens da Meta quando meu cliente usa a API Oficial?

O próprio cliente, na conta Meta (WABA) dele. A D-API cobra de você apenas o preço por conexão.

Teste com o time técnico do seu lado

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

Leia também

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.