integração · node.js e typescript
API WhatsApp Node.js com o SDK oficial d-api-sdk
Use a API WhatsApp Node.js da D-API pelo SDK oficial d-api-sdk: criar a conexão do cliente, mostrar o QR, enviar mensagens e baixar mídia com tipos TypeScript, sem escrever cliente HTTP do zero.
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
Tipado de ponta a ponta
Opções e respostas com tipos TypeScript. Pacote com build ESM e CommonJS, instalado por npm, yarn ou pnpm.
Módulos por domínio
sessions, messages, interactive, chats, contacts, groups, labels, media, history, calls e mais, num só cliente.
Erro com status HTTP
Toda falha vira um erro com status e corpo da resposta. Timeout padrão de 30 segundos, configurável.
Connect da API Oficial
O entry d-api-sdk/connect abre o Embedded Signup hospedado pela D-API dentro do seu frontend.
A API WhatsApp Node.js da D-API tem um SDK oficial, o d-api-sdk, escrito em TypeScript. Para um SaaS com backend em Node, isso significa trocar dezenas de fetch montados à mão por chamadas tipadas, com autocomplete de cada campo e erro padronizado. Esta página mostra o que o SDK cobre e como usá-lo no fluxo que todo SaaS precisa: conectar o número do cliente, enviar, receber e lidar com falhas.
O exemplo é uma plataforma de agendamento para salões de beleza, em que cada salão conecta o próprio WhatsApp para mandar lembretes e conversar com clientes.
Instalar e configurar o SDK de WhatsApp para Node
npm install d-api-sdk
import { DApi } from 'd-api-sdk';
export const dapi = new DApi({
apiKey: process.env.DAPI_API_KEY!,
timeout: 15_000,
});
O baseUrl padrão é https://api.d-api.cloud, e o timeout padrão é de 30 segundos. A chave vai no header Authorization de cada requisição. O pacote publica build ESM e CommonJS com os tipos juntos, então funciona em projetos com import ou require.
O que cada módulo cobre
O cliente DApi agrupa as rotas por domínio. Os módulos que um SaaS usa no dia a dia:
| Módulo | Métodos principais |
|---|---|
sessions |
create, list, get, getQRCode, getPairCode, connect, disconnect, delete, updateWebhookConfig, updateRabbitMQConfig, getLogs |
messages |
sendText, sendImage, sendVideo, sendAudio, sendDocument, sendSticker, sendLocation, sendContact, sendPoll, sendReaction, sendAlbum, edit |
interactive |
sendList, sendCarousel, sendTemplate, sendNativeFlow, sendPix |
chats |
list, get, listMessages, sendPresence, markAsRead, deleteMessage |
contacts |
list, get, getAvatar, checkNumbers, getBlocklist, updateBlocklist |
labels, groups, media, history |
Etiquetas, grupos, download de mídia e sincronização de histórico |
calls, voice, sms |
Ligações de WhatsApp, URA e SMS |
Todos chamam a mesma API REST documentada em OpenAPI 3. Se um campo novo aparecer na API antes da próxima versão do SDK, a rota continua acessível por fetch com o mesmo header.
Conectar o número do cliente
O momento de maior atrito no onboarding do salão é conectar o WhatsApp. O resultado que você quer é uma tela no seu produto com o QR code, que some sozinha quando o número conecta.
export async function iniciarConexao(salaoId: string) {
const sessionId = `salao-${salaoId}`;
await dapi.sessions.create({
sessionId,
connectionMode: 'qr',
webhookUrl: `https://agenda.seu-saas.com/hooks/whatsapp/${process.env.WA_HOOK_TOKEN}`,
ignoreGroups: true,
});
const qr = await dapi.sessions.getQRCode(sessionId);
return { sessionId, qrCodeImage: qr.qrCodeImage, status: qr.status };
}
O qrCodeImage vem como data URL PNG em base64, pronto para um <img>. Para o salão que prefere conectar pelo número de telefone, crie a sessão com connectionMode: 'pair' e pairPhone, e mostre o código de getPairCode(sessionId). Os eventos connection.qrcode e connection.status avisam o seu backend de QR novo e de conexão concluída. O desenho completo da tela, com a sua marca, está em WhatsApp white label para SaaS.
Enviar lembretes e mídia
Com a sessão conectada, o lembrete do dia seguinte é uma chamada:
await dapi.messages.sendText({
sessionId: 'salao-482',
to: '5511999999999',
text: 'Oi, Júlia. Seu horário de corte é amanhã às 15h. Responda SIM para confirmar.',
});
Para imagem, documento e áudio, os métodos seguem o mesmo padrão, trocando text por image, document ou audio, com caption, fileName e ptt onde se aplica. Em envios pesados ou em lote, passe async: 'true': a API responde na hora com um commandId e entrega o resultado no webhook command.result, como explica o guia de comandos assíncronos.
Para a conversa parecer humana enquanto o seu sistema prepara a resposta, chats.sendPresence({ sessionId, to, presence: 'typing', durationMs: 3000 }) mostra “digitando” do outro lado.
Receber eventos e responder
O SDK cuida das chamadas de saída. A entrada é um webhook, um POST JSON que qualquer servidor Node recebe. O padrão que funciona em produção é confirmar rápido, publicar numa fila interna e deixar o worker usar o SDK.
import express from 'express';
import { dapi } from './dapi';
const app = express();
app.use(express.json());
app.post('/hooks/whatsapp/:token', async (req, res) => {
if (req.params.token !== process.env.WA_HOOK_TOKEN) return res.sendStatus(401);
res.sendStatus(200);
const { event, sessionId, data } = req.body;
if (event !== 'messages.received' || data.fromMe || data.is_group) return;
if (data.type === 'text' && data.message.trim().toUpperCase() === 'SIM') {
await agenda.confirmarPorTelefone(sessionId, data.from.jid);
await dapi.messages.sendText({
sessionId,
to: data.from.jid.split('@')[0],
text: 'Horário confirmado. Até amanhã!',
});
}
});
O webhook tem timeout de 30 segundos por tentativa e até 7 tentativas com backoff exponencial, por isso o res.sendStatus(200) vem antes de qualquer trabalho. Em produção, troque o processamento inline por uma fila e trate data.id como chave de idempotência. Os payloads de cada evento estão no catálogo de eventos de webhook.
Para mídia recebida, o evento já traz media_url com o arquivo armazenado. Quando a conta usa a opção de não armazenar mídias, dapi.media.download recebe media_key, mimetype e direct_path ou url do próprio evento e devolve o conteúdo em base64.
Tratar erros do SDK
Toda resposta fora da faixa 2xx vira um erro com status e response, o corpo devolvido pela API. Timeout vira um erro com status: 408. Isso permite separar o que vale repetir do que é erro de dado:
try {
await dapi.messages.sendText({ sessionId, to, text });
} catch (err: any) {
if (err.status === 408 || err.status >= 500) return agendarNovaTentativa({ sessionId, to, text });
logger.warn({ sessionId, status: err.status, body: err.response }, 'envio recusado');
}
O SDK não repete chamadas sozinho, de propósito. Reenviar uma mensagem que pode ter saído duplica o lembrete, e quem sabe se a repetição é segura é o seu código. Para envios em que isso importa, o modo assíncrono com command.result dá a resposta definitiva de cada envio.
API Oficial e ligações no mesmo pacote
Dois entries completam o SDK. O d-api-sdk/connect roda no navegador e abre o Embedded Signup hospedado pela D-API para o cliente conectar um número da API Oficial, autenticado por uma publishable key que só inicia o onboarding. O connectionId devolvido vira o sessionId nas mesmas rotas de envio.
O módulo calls e a classe LiveCall levam ligações de WhatsApp para dentro do produto. O backend inicia a chamada com dapi.calls.stream e entrega ao navegador só o callId e a URL; no Node, dapi.calls.start entrega áudio PCM de 16 kHz para um agente de voz. O transporte recomendado é WebRTC, com fallback para WebSocket. A página de ligação de WhatsApp no navegador mostra esse fluxo.
Sem Node no backend
Se parte do seu stack roda em outra linguagem, o contrato é o mesmo: os métodos do SDK são uma camada fina sobre a REST. Os guias para Python e PHP, listados abaixo, mostram as mesmas operações com cliente HTTP comum. A referência completa de cada rota está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
O SDK roda no navegador?
O pacote funciona em Node e no navegador, mas a API key é secreta e fica no backend. No frontend, use só o d-api-sdk/connect com uma publishable key ou o LiveCall, que recebe do seu backend apenas o callId e a URL da chamada.
O SDK faz retentativa automática?
Não. O cliente faz uma requisição por chamada, com timeout configurável, e lança o erro com o status HTTP. A política de retentativa fica com o seu código, que sabe o que pode ser repetido.
Preciso do SDK para receber webhooks?
Não. O webhook é um POST JSON para a sua URL e qualquer servidor HTTP em Node recebe. O SDK entra quando você responde, consulta chats ou baixa mídia.
Qual versão de Node o SDK pede?
Para chamadas REST, qualquer Node com fetch global. Para ligações ao vivo, abaixo do Node 22 é preciso instalar ws ou passar um WebSocket, e o transporte WebRTC no Node depende do pacote @roamhq/wrtc.