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

automação e ia

Agente de IA no WhatsApp com SDK Node e servidor MCP

Como colocar um agente de IA no WhatsApp do seu SaaS: webhook e SDK Node para o fluxo controlado, servidor MCP para o agente agir sozinho.

Time D-API. Atualizado em .8 min de leitura.

Colocar um agente de IA no WhatsApp do seu produto deixou de ser projeto de trimestre. Com a infraestrutura de conexão resolvida, o trabalho que sobra para o seu time é o que diferencia o produto: o prompt, as ferramentas do agente e as regras de quando ele passa a conversa para um humano. Receber mensagem, manter a sessão viva e entregar a resposta ficam com a D-API.

Existem dois caminhos para isso, e eles resolvem problemas diferentes. O primeiro é o clássico: o webhook avisa que chegou mensagem, o seu backend chama o modelo e responde com o SDK Node d-api-sdk. O segundo é o servidor MCP da D-API, que expõe as ações do WhatsApp como ferramentas para o agente usar por conta própria.

Este artigo mostra os dois com código real, explica quando cada um faz sentido e lista os cuidados de produção que separam uma demo de um recurso que o seu cliente paga.

O que um agente precisa para operar no WhatsApp

Todo agente conversacional faz quatro coisas: percebe que chegou mensagem, monta contexto, decide o que fazer e responde. No WhatsApp, cada etapa tem um detalhe que costuma aparecer só em produção.

Perceber a mensagem exige uma conexão estável e um canal de eventos confiável, com reentrega quando o seu endpoint oscila. Montar contexto exige histórico da conversa, nome do contato e, em muitos casos, dados do seu próprio sistema. Responder exige saber se a conexão é oficial ou não-oficial, porque a regra da janela de 24 horas muda o que pode ser enviado.

Quanto mais dessas peças vêm prontas, mais o seu time fica no que importa: a qualidade da resposta do agente.

Caminho 1: webhook e SDK Node, com o seu backend no controle

Esse é o caminho para atendimento em produção. O seu backend recebe o evento, aplica as suas regras (horário, plano do cliente, limites de uso), chama o modelo e devolve a resposta. Você tem log de tudo, controla custo de tokens e decide quando escalar para humano.

Instalar e inicializar

npm install d-api-sdk
import { DApi } from 'd-api-sdk';

const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY! });

Receber messages.received e responder

O evento chega com o envelope padrão (event, sessionId, timestamp, traceId, data). Os campos que o agente usa ficam em data: o texto em message, o tipo em type, o remetente em from.jid e from_name, além de fromMe e is_group.

import express from 'express';
import { DApi } from 'd-api-sdk';

const app = express();
app.use(express.json());

const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY! });

app.post('/hooks/dapi/:token', (req, res) => {
  // Confirma rápido: o processamento do modelo pode passar do timeout do webhook.
  res.sendStatus(200);

  const { event, sessionId, data } = req.body;
  if (event !== 'messages.received') return;
  if (data.fromMe || data.is_group || data.type !== 'text') return;

  void responder(sessionId, data);
});

async function responder(sessionId: string, data: any) {
  const to = data.from.jid.split('@')[0];

  await dapi.chats.sendPresence({ sessionId, to, presence: 'typing', durationMs: 3000 });

  // Seu agente: prompt, ferramentas, histórico, regras de handoff.
  const text = await meuAgente.responder({
    sessionId,
    contato: data.from_name,
    mensagem: data.message,
  });

  await dapi.messages.sendText({ sessionId, to, text });
}

O sendPresence com typing mostra “digitando” enquanto o modelo pensa, o que reduz a sensação de robô travado. Para dar memória ao agente, dapi.chats.listMessages(chatId, { sessionId, limit }) traz as últimas mensagens da conversa.

Por que confirmar o webhook antes de chamar o modelo

A entrega de webhook da D-API tem timeout de 30 segundos por tentativa e até 7 tentativas com backoff exponencial. Uma chamada de modelo com ferramentas pode passar disso. Se o seu endpoint responde só depois do modelo, o evento entra em retentativa e o agente responde duas vezes. Por isso o exemplo devolve 200 primeiro. Em produção, troque o void responder(...) por uma fila com worker. Os detalhes de envelope, reentrega e deduplicação estão na documentação da D-API e no artigo sobre webhooks do WhatsApp.

Se o seu volume pede mais controle de vazão, cada sessão pode publicar os eventos numa fila RabbitMQ própria, e os seus workers consomem no ritmo que o orçamento de tokens permite.

Caminho 2: servidor MCP, com o agente usando o WhatsApp como ferramenta

O Model Context Protocol padroniza como um agente descobre e chama ferramentas externas. O servidor MCP da D-API transforma a API de WhatsApp nessas ferramentas. O resultado prático: um agente em qualquer cliente compatível com MCP passa a enviar mensagens, consultar conversas, gerenciar grupos e contatos sem que o seu time escreva uma linha de integração.

Configurar o conector

O servidor fala Streamable HTTP em https://api.d-api.cloud/mcp e autentica pela mesma API key da API REST, no header Authorization. Em clientes que aceitam servidor remoto:

{
  "mcpServers": {
    "d-api-whatsapp": {
      "url": "https://api.d-api.cloud/mcp",
      "headers": {
        "Authorization": "<SUA_API_KEY>"
      }
    }
  }
}

Clientes que só aceitam stdio usam uma ponte via npx:

{
  "mcpServers": {
    "d-api-whatsapp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.d-api.cloud/mcp",
        "--header",
        "Authorization:${DAPI_API_KEY}"
      ],
      "env": { "DAPI_API_KEY": "<SUA_API_KEY>" }
    }
  }
}

Quais ferramentas o agente recebe

As ferramentas são geradas a partir da especificação OpenAPI da própria API. Cada endpoint vira uma ferramenta com nome derivado do método e do caminho, como post_api_v1_messages_send_text para envio de texto ou get_api_v1_chats para listar conversas. Quando a API ganha um endpoint novo, ele aparece como ferramenta sem atualização no seu lado. As chamadas passam pela mesma autenticação da REST, então o agente tem exatamente as permissões da API key que você configurou.

Para receber, existe a ferramenta poll_messages. Ela entrega as mensagens que chegaram nas sessões da chave, da mais antiga para a mais nova, com limit de 1 a 200 (padrão 50). A leitura é destrutiva: a mensagem retornada sai do buffer e é entregue uma única vez.

Fixar o conector numa sessão

Num SaaS com muitos clientes, você quer que o agente do cliente A nunca toque na sessão do cliente B. Basta acrescentar o parâmetro na URL:

https://api.d-api.cloud/mcp?sessionId=cliente-a

Com o conector fixado, o campo sessionId some do esquema de todas as ferramentas, o valor é injetado na execução (sobrescrevendo o que o modelo mandar) e o poll_messages lê só o buffer daquela sessão. Como quem define a URL é quem configura o conector, o modelo não tem como mudar isso. A fixação só restringe: fixar numa sessão que a API key não enxerga não libera nada. Esse desenho conversa com o que discutimos sobre arquitetura multi-tenant.

Quando usar cada caminho

Use webhook e SDK quando o agente atende clientes finais em tempo real. Você precisa de latência baixa, resposta a cada mensagem, log por conversa, controle de custo e regra de handoff. O seu backend fica no meio, e isso é uma vantagem.

Use o servidor MCP quando o agente opera o WhatsApp como uma das suas ferramentas. Exemplos: um assistente interno que resume as conversas do dia e responde pendências, um agente de prospecção que envia mensagens a partir de uma planilha, ou um copiloto para o time de suporte do seu cliente. Também é o caminho mais rápido para prototipar: em minutos o agente já envia mensagem, e você valida o comportamento antes de escrever o backend.

Os dois convivem na mesma conta, nas mesmas conexões. Um padrão comum é atender pelo webhook e usar o MCP para tarefas assíncronas do time.

Cuidados de produção para agentes no WhatsApp

Idempotência

Mesmo com deduplicação no lado da D-API, trate data.id como chave de idempotência. Guarde os IDs processados e ignore repetidos. Um agente que responde duas vezes à mesma pergunta perde a confiança do usuário rápido.

Origem do webhook

Os webhooks não levam assinatura HMAC. A recomendação da documentação é usar uma URL secreta, com token no caminho (como no exemplo /hooks/dapi/:token), e validar o User-Agent e o sessionId esperado.

Handoff para humano

Defina gatilhos claros: pedido explícito, baixa confiança do modelo, assunto sensível. Quando o humano assume, marque a conversa no seu sistema para o agente parar de responder. As mensagens enviadas pelo atendente no celular chegam como messages.received com fromMe: true, e o filtro do exemplo já impede o agente de reagir a elas.

API Oficial e janela de 24 horas

Na API Oficial, o agente responde livremente dentro da janela aberta pelo cliente. Fora dela, a primeira mensagem precisa ser um template aprovado, cobrado pela Meta na conta do cliente final, com valores publicados na tabela de preços da Meta. Com webhookMode: "normalized", o evento de uma conexão oficial chega no mesmo formato da não-oficial, então o mesmo handler serve as duas. O artigo sobre API oficial e não-oficial na mesma integração mostra como isso funciona.

A base que o agente herda

Um agente só é tão bom quanto a conexão por trás dele. A D-API opera 1.875 conexões em 4 datacenters no Brasil, com 99,9% de uptime garantido em contrato, conexões isoladas e IPs dedicados. Reconexão, reentrega de eventos e atualização de protocolo ficam com a gente. O seu time cuida do prompt e das ferramentas.

Por onde começar

Se você quer validar a ideia hoje, configure o servidor MCP no seu cliente de agente, fixe numa sessão de teste e peça ao agente para enviar uma mensagem e ler as respostas com poll_messages. Em uma tarde você sabe se o comportamento convence.

Se o objetivo é um recurso de produto, comece pelo webhook e pelo SDK: endpoint com token secreto, confirmação imediata, fila, idempotência por data.id e sendText no final. Depois acrescente histórico com listMessages, presença de digitação e as regras de handoff. O preço por conexão cai com o volume e está na tabela de preços.

Veja também: Integração, Para SaaS.

Perguntas frequentes

Preciso escolher entre SDK e MCP?

Não precisa. Muitos produtos usam os dois: o webhook e o SDK cuidam do atendimento em tempo real, com regras e logs no seu backend, e o MCP fica para agentes que operam o WhatsApp como ferramenta, como um assistente interno ou um agente de prospecção.

O servidor MCP consegue ler mensagens recebidas?

Consegue, pela ferramenta poll_messages. Ela entrega as mensagens que chegaram nas sessões da API key, da mais antiga para a mais nova, com limite de 1 a 200 por chamada. A leitura remove a mensagem do buffer, então cada mensagem é entregue uma vez.

Como impedir que o agente de um cliente mande mensagem pela sessão de outro?

Fixe o conector numa sessão adicionando ?sessionId= na URL do MCP. O parâmetro some do esquema das ferramentas, é injetado na execução e só restringe: a API key continua decidindo o que é acessível.

Funciona com a API Oficial da Meta?

Funciona. A conexão oficial usa o mesmo sessionId e, no modo normalized, entrega o mesmo evento messages.received da não-oficial. A diferença é a regra da janela de 24 horas: fora dela, a primeira mensagem precisa ser um template aprovado.

Qual SDK usar com Python ou outra linguagem?

O SDK oficial é para Node. Em outras linguagens, a API REST é a mesma que o SDK chama por baixo, e o servidor MCP funciona com qualquer cliente MCP, independente da linguagem do agente.

Teste com o time técnico do seu lado

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

Leia também

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.