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.