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(unofficialoucloud_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:
- 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. - Ouvir o evento
connection.qrcodeno 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/sessionslista as sessões com paginação, busca e filtros (comotype=cloud_api), útil para reconciliar o seu banco com o estado real.GET /api/v1/sessions/{sessionId}/connectreconecta 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.