vários números, uma integração
API WhatsApp para múltiplos números, com um cliente por conexão
Com a API WhatsApp para múltiplos números da D-API, cada cliente do seu SaaS conecta o próprio número numa instância isolada, com webhook próprio e o mesmo código de integração do primeiro ao milésimo número.
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 sessionId por cliente
Você escolhe o identificador de cada conexão e usa o mesmo valor em todas as rotas e em todos os eventos.
Webhook por número ou por evento
Cada sessão tem a própria URL de webhook, com envio de todos os eventos para um destino ou um destino por evento.
Isolamento por instância
Cada número roda na própria instância, com proxy atribuído. Um problema num cliente não derruba os outros.
Oficial e não-oficial juntas
Conexões da Cloud API e da não-oficial convivem na mesma conta, com payload de webhook no mesmo formato.
Uma API WhatsApp para múltiplos números é a base de qualquer SaaS que dá WhatsApp aos próprios clientes. O CRM tem 400 empresas, cada uma com o seu número. O software de clínica tem uma conexão por unidade. A plataforma de delivery tem um número por restaurante. Em todos esses casos, o problema deixa de ser “como mandar uma mensagem” e passa a ser “como operar centenas de números sem que um afete o outro e sem reescrever a integração a cada cliente novo”.
Na API de WhatsApp da D-API, cada número é uma sessão com identificador próprio, instância isolada e configuração própria. O código que conecta o primeiro cliente é o mesmo que conecta o milésimo.
Uma conexão por cliente, um sessionId por conexão
O POST /api/v1/sessions cria a conexão. O sessionId é escolhido por você e reaparece em todas as rotas e em todos os eventos do webhook. Se ele carrega o identificador do seu tenant, o roteamento fica trivial: o evento chega, você lê o sessionId e sabe de quem é.
curl -X POST https://api.d-api.cloud/api/v1/sessions \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "cliente-4821",
"connectionMode": "qr",
"webhookUrl": "https://seu-saas.com.br/webhooks/whatsapp/cliente-4821",
"ignoreGroups": true,
"ignoreStatus": true,
"receiveCalls": false
}'
Cada sessão tem as próprias configurações. ignoreGroups e ignoreStatus (ambos true por padrão) cortam eventos de grupos e de status para o cliente que não usa. receiveCalls liga o recebimento de ligações só para quem contratou essa feature no seu produto. historySync traz o histórico do aparelho ao conectar. Todos os campos estão na documentação da D-API.
Um cuidado no desenho: trate o sessionId como imutável. Ele é a chave que liga a conexão ao seu tenant em todas as rotas e eventos. Se o cliente troca de número, apague a sessão antiga e crie outra, em vez de reaproveitar o identificador para outro cliente, o que misturaria histórico e eventos de duas empresas.
Conectando o número do seu cliente
O cliente final conecta o número dele de dentro do seu painel, sem acessar a D-API. Na API não-oficial há dois caminhos:
- QR code.
GET /api/v1/sessions/{sessionId}/qrdevolve o QR em JSON ou, com?image=1, como PNG pronto para exibir. O eventoconnection.qrcodeentrega cada QR novo. A página de QR code pela API detalha esse fluxo. - Código de pareamento. Com
connectionMode: "pair"e opairPhone, o cliente digita um código no celular em vez de escanear. Útil quando ele está no celular e não tem outra tela. Veja o código de pareamento.
Para a API Oficial, o SDK Node tem uma entrada de navegador, d-api-sdk/connect, que abre o Embedded Signup hospedado pela D-API com uma chave publicável. O número oficial do seu cliente é conectado de dentro do seu SaaS, sem que o seu domínio precise ser registrado na Meta.
Webhook por número ou um destino central
Cada sessão define o seu webhook, e o webhookConfig decide o formato:
type |
Como funciona | Quando usar |
|---|---|---|
single |
Todos os eventos vão para a mesma URL | Um endpoint central que roteia pelo sessionId |
per_event |
Cada evento tem a sua webhookUrl |
Mensagens num serviço, ligações em outro, status de conexão no monitoramento |
Evento ausente ou com enabled: false não é enviado. Assim, o cliente que só usa notificações não gera eventos de presença no seu servidor. Para arquiteturas por fila, cada sessão também pode publicar numa fila RabbitMQ própria.
Operando centenas de números
Com a base crescendo, três rotas viram ferramenta diária do seu time:
- Listagem paginada.
GET /api/v1/sessionslista as sessões da conta compageelimit(até 100 por página), busca por texto e filtros porstatus, portype(unofficialoucloud_api) e porreceiveCalls. A resposta traztotal,totalPagesestatusCounts, a contagem por status do conjunto filtrado inteiro, ótima para um painel de “quantos clientes estão desconectados agora”. - Reconexão de um número.
GET /api/v1/sessions/{sessionId}/connectreinicia a instância daquela sessão, sem tocar nas outras. - Remoção.
DELETE /api/v1/sessions/{sessionId}apaga a sessão e desconecta o WhatsApp, quando o cliente cancela o seu produto.
Para o atendimento, o POST /api/v1/chats/search aceita uma lista de sessionIds. Lista vazia busca em todas as sessões da conta, o que permite um inbox unificado para o cliente que tem vários números. A página de gestão de conversas mostra esse fluxo.
Isolamento: o cliente com problema não derruba os outros
Cada número roda na própria instância, com proxy atribuído a ele. Se a conexão de um restaurante cai, os outros 399 continuam enviando e recebendo. A recuperação também é por instância: reinício automático da que travou e troca de proxy quando ele falha, como descreve a página de IP dedicado.
Do seu lado, o isolamento pede uma regra: toda chamada carrega o sessionId do tenant que está agindo, e o seu backend confere que aquele sessionId pertence a ele antes de chamar a API. O artigo sobre API de WhatsApp multi-tenant aprofunda esse desenho, com roteamento de eventos e validação por tenant.
Oficial e não-oficial na mesma base
Muitos SaaS têm clientes nas duas modalidades: o pequeno comércio no número que já usa, a rede de clínicas com número verificado na Oficial. Na D-API, as duas convivem na mesma conta, somam na mesma faixa de preço e, com o webhook no modo normalized, entregam eventos no mesmo formato. Um handler só atende as duas, e o tipo de cada conexão fica no filtro type da listagem. O artigo sobre API Oficial e não-oficial na mesma integração mostra onde cada uma se diferencia.
A cobrança acompanha a escala: por conexão ativa, com preço por conexão que cai conforme o total cresce. A lógica completa está na página de preço da API de WhatsApp.
Time D-API. Atualizado em .
Perguntas frequentes
Existe limite de números por conta?
O plano é por conexão ativa, com instâncias ilimitadas: você paga pelas conexões que estão em uso, e o preço por conexão cai conforme o total cresce.
Posso usar o ID do meu cliente como sessionId?
Sim. O sessionId é escolhido por você na criação da sessão. Um padrão comum é derivar do ID do tenant, como cliente-4821, para rotear eventos sem tabela de tradução.
Consigo mandar cada número para um webhook diferente?
Sim. Cada sessão recebe o próprio webhookUrl, e o webhookConfig aceita type single (todos os eventos na mesma URL) ou per_event (uma URL por evento).
Como mostro ao meu cliente o QR code para conectar o número dele?
GET /api/v1/sessions/{sessionId}/qr devolve o QR code em JSON ou, com image=1, como imagem PNG para exibir no seu painel. O evento connection.qrcode também entrega cada QR novo. Também há o código de pareamento, com connectionMode pair.
Os números da API Oficial entram na mesma conta?
Sim. As conexões cloud_api ficam na mesma conta e somam na mesma faixa de preço. No webhook em modo normalized, o evento tem o mesmo formato de uma conexão não-oficial.