integração · white label
WhatsApp white label para SaaS: o cliente conecta o número dentro do seu produto
Ofereça WhatsApp white label no seu SaaS: a tela de conexão, o QR code, o código de pareamento e o aviso de desconexão ficam no seu produto, com a sua marca, e a D-API fica invisível por trás da API.
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
QR code na sua tela
GET /qr devolve a imagem PNG em base64, e o evento connection.qrcode avisa cada QR novo. O layout é todo seu.
Código de pareamento
Para quem conecta pelo número de telefone, a sessão em modo pair gera o código que o cliente digita no WhatsApp.
Estado da conexão em tempo real
connection.status informa conectado, desconectado, logout e QR expirado, com nome e telefone da conta.
API key só no seu backend
O navegador conversa com o seu servidor, e o seu servidor fala com a D-API. Nenhuma credencial vai para o cliente.
WhatsApp white label para SaaS quer dizer uma coisa concreta: o seu cliente conecta o número de WhatsApp dele sem sair do seu produto e sem saber qual infraestrutura está por trás. Ele vê o seu logo, o seu texto de ajuda e o seu suporte. Para o seu SaaS, isso significa onboarding sem atrito e um recurso que parece nativo, e não uma integração com terceiro colada na lateral.
Esta página mostra o que a D-API oferece para construir essa experiência e o que fica com o seu time. O exemplo é uma plataforma de atendimento para escolas de idiomas, em que a secretaria de cada escola conecta o WhatsApp no primeiro acesso.
O que white label significa aqui
Na prática, white label aqui é construir a experiência no seu produto sobre a API da D-API. Todo o ciclo da conexão, da criação à desconexão, é exposto por endpoint e por evento, então nenhuma etapa obriga o seu cliente a abrir o painel da D-API.
| Etapa | Na D-API | No seu produto |
|---|---|---|
| Criar a conexão | POST /api/v1/sessions |
Botão “Conectar WhatsApp” |
| Mostrar o QR | GET /api/v1/sessions/{sessionId}/qr e connection.qrcode |
Tela com a sua marca e instruções |
| Código de pareamento | GET /api/v1/sessions/{sessionId}/pair-code e connection.paircode |
Alternativa para quem não consegue escanear |
| Confirmar conexão | connection.status com connected |
“Conectado como Escola Talk” |
| Avisar queda | connection.status com logged_out ou disconnected |
Banner pedindo reconexão |
Criar a conexão pelo seu backend
A API key é secreta, então a chamada sai do seu servidor. Quando a secretaria clica em “Conectar WhatsApp”, o backend cria a sessão com um sessionId ligado ao tenant:
curl -X POST https://api.d-api.cloud/api/v1/sessions \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "escola-talk-centro",
"type": "unofficial",
"connectionMode": "qr",
"webhookUrl": "https://app.seu-saas.com/hooks/whatsapp/TOKEN",
"ignoreStatus": true
}'
Um sessionId estável por número, como escola-talk-centro, evita uma tabela de tradução: o mesmo valor aparece em todo evento e em toda rota de envio.
A tela de QR code com a sua marca
O seu frontend pede o QR ao seu backend, que repassa a chamada à D-API. A resposta de GET /api/v1/sessions/{sessionId}/qr traz status, qrCode com o texto do QR, qrCodeImage com a imagem PNG em data URL e qrCodeUpdatedAt. Com ?image=1, a rota devolve o PNG direto, útil se o seu backend só faz proxy da imagem.
{
"sessionId": "escola-talk-centro",
"status": "connecting",
"qrCode": "2@abc...",
"qrCodeImage": "data:image/png;base64,iVBOR...",
"qrCodeUpdatedAt": "2026-11-15T13:02:11.000Z",
"expired": false
}
Se você prefere desenhar o QR com o próprio componente, use o texto de qrCode; a imagem pronta serve para quem quer só um <img>. Quando o QR expira, a resposta vem com expired: true e uma imagem de expirado; consulte de novo em alguns segundos para pegar o próximo. Para não depender de polling, o evento webhook connection.qrcode traz qr e qrImage a cada QR novo, e QR idêntico ao anterior não gera evento. Um canal em tempo real do seu backend para o navegador fecha o ciclo.
O restante da tela é seu: as instruções no tom do seu produto, o vídeo curto de ajuda, o link para o seu suporte. A página sobre API WhatsApp QR code aprofunda os detalhes do QR.
Código de pareamento para quem não consegue escanear
A secretária que configura o sistema no próprio celular não tem como apontar a câmera para a tela do mesmo aparelho. Para ela, o código de pareamento resolve. Crie a sessão com "connectionMode": "pair" e "pairPhone" com o número a conectar, com DDI e só dígitos, e mostre o pairCode de GET /api/v1/sessions/{sessionId}/pair-code. O evento connection.paircode traz o mesmo code e o phone. No WhatsApp, ela abre Aparelhos conectados, escolhe conectar com número de telefone e digita o código. O passo a passo está em código de pareamento do WhatsApp.
Conectado, desconectado e de volta
Quando a leitura dá certo, connection.status chega com status: "connected", além de jid, phone, name e, quando disponível, profilePictureUrl. É o que permite fechar a tela de onboarding com “Conectado como Escola Talk”, mostrando a foto do perfil, sem nenhuma consulta extra.
Os outros estados pedem ação do seu produto:
logged_out: o aparelho foi removido, comreasoncomodevice_removed. Mostre um banner pedindo reconexão e reabra a tela de QR.disconnected: a conexão caiu. Trate junto comlogged_outno alerta ao cliente.qrcode_timeout: a sessão passou 45 minutos gerando QR sem leitura e sem pedido de QR, e a D-API hibernou a geração. Nada é apagado. Quando a secretaria voltar à tela, o primeiro pedido de QR acorda a sessão, e cada pedido zera a contagem.
O logout nunca chega como evento separado, sempre como connection.status. Um handler que procura um evento logged_out próprio nunca dispara.
Onboarding oficial a partir do seu produto
Alguns clientes vão pedir a API Oficial da Meta. Aqui, o white label é parcial e vale dizer isso ao seu time comercial. O Embedded Signup da Meta não roda no domínio do seu SaaS, então a D-API hospeda o fluxo e o d-api-sdk/connect abre essa página como popup a partir do seu produto, autenticado por uma publishable key que só inicia o onboarding. O seu domínio não precisa ser cadastrado na Meta.
Você passa metadata com o seu identificador de tenant, até 512 bytes de JSON, e recebe de volta o connectionId no navegador e no webhook session.created. No celular, o popup abre como aba e o retorno ao navegador pode não acontecer, então confirme pela chegada do session.created antes de mostrar erro. Depois disso, o connectionId é o sessionId das mesmas rotas de envio.
O que fica com o seu time
A D-API entrega a conexão, os eventos e a estabilidade: conexão isolada por número, proxy com IP dedicado, monitoramento com reinício automático, 4 datacenters no Brasil e 99,9% de uptime garantido em contrato. O seu time fica com a experiência: a tela de conexão, os textos, o canal em tempo real até o navegador e o suporte ao seu cliente. É essa divisão que deixa o recurso com cara de produto seu.
A referência dos eventos de conexão está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
O meu cliente precisa ter conta na D-API?
Não. As conexões ficam na conta do seu SaaS, uma sessão por número. O seu cliente só interage com a tela que você construiu.
Qual nome aparece no WhatsApp do meu cliente depois de conectar?
O número continua sendo o do seu cliente, com o nome e a foto de perfil dele. Para os contatos dele, nada muda: as mensagens saem do mesmo número de sempre.
Dá para fazer white label também na API Oficial?
Em parte. O onboarding oficial roda o Embedded Signup da Meta num popup hospedado pela D-API, aberto a partir do seu produto pelo d-api-sdk/connect. O resto, envio e webhook, segue pela sua integração.
O QR code expira enquanto o cliente decide?
O QR se renova sozinho enquanto a tela pede QR. Se a sessão passar 45 minutos gerando QR sem leitura e sem nenhum pedido, ela hiberna, e o próximo pedido de QR acorda a sessão.