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

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.

A gente também é SaaS

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

Continue por aqui

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.