integração · mcp e agentes
Agente de IA no WhatsApp com MCP: o passo a passo para conectar o seu
Coloque o seu agente de IA no WhatsApp com MCP em poucos passos: aponte o cliente MCP para a D-API, prenda o conector na sessão do cliente certo e deixe o agente ler com poll_messages e responder pelas ferramentas de envio.
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
Um endpoint, a mesma API key
Streamable HTTP em https://api.d-api.cloud/mcp, autenticado pelo header Authorization, como na REST.
Ferramentas geradas da OpenAPI
Cada rota liberada vira uma ferramenta, com nome do método e do caminho, como post_api_v1_messages_send_text.
Conector preso a um cliente
Com ?sessionId= na URL, o campo some das ferramentas e o agente só age naquela sessão.
Leitura sem webhook
poll_messages devolve as mensagens recebidas, da mais antiga para a mais nova, de 1 a 200 por chamada.
Um agente de IA no WhatsApp com MCP deixa o seu time escrever o comportamento do agente e pular a integração. O Model Context Protocol padroniza como um agente descobre e chama ferramentas, e o servidor MCP da D-API publica as ações do WhatsApp nesse formato. O agente passa a enviar mensagem e ler respostas como faz com qualquer outra ferramenta.
Esta página é o roteiro prático para conectar. A discussão sobre quando usar MCP e quando usar webhook com SDK está no artigo sobre agentes de IA no WhatsApp. Aqui o foco é fazer funcionar, com o exemplo de um SaaS de imobiliárias que oferece a cada imobiliária cliente um agente que qualifica interessados.
Antes de conectar: chave, sessão e escopo
Três decisões evitam retrabalho:
- Qual API key. O agente terá exatamente as permissões dessa chave. As ferramentas chamam a API pela mesma autenticação da REST.
- Qual sessão. Num SaaS, cada imobiliária tem a própria sessão. Um agente que atende uma imobiliária deve enxergar só a sessão dela.
- Quem configura o conector. O parâmetro que prende o conector à sessão fica na URL, definida por quem configura, e não pelo modelo. É isso que impede o agente de um cliente de agir no número de outro.
Passo 1: a URL do conector
O servidor fala Streamable HTTP, sem estado entre requisições, no endereço abaixo. A versão com sessionId prende o conector a uma sessão:
https://api.d-api.cloud/mcp
https://api.d-api.cloud/mcp?sessionId=imob-vista-mar
Com o conector preso, o campo sessionId some do esquema de todas as ferramentas, e o valor da URL é injetado em cada execução, por cima de qualquer coisa que o modelo mande. O modelo nem vê a opção de escolher outra sessão.
Passo 2: configurar o cliente MCP
Em clientes de agente que aceitam servidor remoto por HTTP, a configuração é a URL e o header de autenticação:
{
"mcpServers": {
"whatsapp-vista-mar": {
"url": "https://api.d-api.cloud/mcp?sessionId=imob-vista-mar",
"headers": { "Authorization": "<SUA_API_KEY>" }
}
}
}
Se o agente roda no seu backend, o cliente MCP vai no código. Em TypeScript, com o SDK oficial do protocolo:
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
export async function conectarWhatsApp(sessionId: string) {
const transport = new StreamableHTTPClientTransport(
new URL(`https://api.d-api.cloud/mcp?sessionId=${encodeURIComponent(sessionId)}`),
{ requestInit: { headers: { Authorization: process.env.DAPI_API_KEY! } } },
);
const client = new Client({ name: 'agente-imobiliaria', version: '1.0.0' });
await client.connect(transport);
return client;
}
A chamada sem chave válida responde 401 com erro JSON-RPC, o que facilita diagnosticar credencial errada logo no primeiro teste.
Passo 3: conferir as ferramentas
Liste as ferramentas antes de escrever o prompt. Elas são geradas a partir da especificação OpenAPI da API: cada rota liberada para o MCP vira uma ferramenta com nome derivado do método e do caminho, em minúsculas, como post_api_v1_messages_send_text para texto e post_api_v1_messages_send_image para imagem. A descrição de cada ferramenta é o resumo da rota na própria API, o que ajuda o modelo a escolher a certa.
O resultado de cada chamada traz o status HTTP e, em caso de sucesso, data com o corpo da resposta. Quando o status é 400 ou maior, o resultado vem marcado como erro, com o corpo em error. Instrua o agente a ler esse campo antes de tentar de novo: um número inválido não melhora com repetição.
Passo 4: ler mensagens com poll_messages
Além das ferramentas geradas da API, o servidor tem poll_messages, para o agente ler o que chegou sem precisar de webhook. Ela aceita limit de 1 a 200, com padrão 50, e devolve count e a lista messages, da mais antiga para a mais nova. Cada item traz sessionId, messageId, from, fromMe, timestamp, type, text e o evento original em raw.
Três comportamentos definem como usar:
- Leitura destrutiva. A mensagem retornada sai do buffer. Cada mensagem é entregue uma vez, então tenha um consumidor por sessão.
- Buffer limitado. Cada sessão guarda as 200 mensagens mais recentes, e o buffer expira uma hora depois da última mensagem recebida. Um agente que fica horas sem ler perde o que passou disso.
- Ordem por sessão. Num conector sem
sessionId, a leitura percorre as sessões da chave uma a uma até completar olimit. Uma sessão movimentada pode ocupar a leitura inteira, mais um motivo para prender o conector.
No exemplo da imobiliária, o loop do agente chama poll_messages, ignora itens com fromMe: true (o corretor respondendo pelo celular), qualifica o interessado e responde com post_api_v1_messages_send_text.
Um conector por cliente do seu SaaS
O desenho que escala é um conector por sessão. Quando uma imobiliária nova ativa o agente, o seu backend cria a conexão com sessionId próprio e abre um cliente MCP com a URL presa naquela sessão. A mesma API key serve a todos, e a separação vem da URL. Se uma imobiliária cancela, basta encerrar o conector dela.
Para tarefas internas do seu time, como um assistente que resume as conversas do dia de várias contas, um conector sem sessionId faz sentido, porque ali o objetivo é justamente enxergar várias sessões.
Do protótipo à produção
O MCP é o caminho mais rápido para ver o agente conversando. Em produção, alguns cuidados se somam:
- Latência. O
poll_messagesdepende da frequência de leitura do agente. Para atendimento em que cada segundo conta, o webhook entrega a mensagem assim que ela chega, e o seu backend aciona o agente. Os eventos disponíveis estão no catálogo de eventos de webhook. - Handoff. Defina no prompt quando o agente para e chama um humano. Mensagens do corretor pelo celular chegam com
fromMe: truee servem de sinal de que alguém assumiu. - API Oficial. Se a imobiliária usa a Cloud API, fora da janela de 24 horas a primeira mensagem precisa ser template aprovado. Ensine isso ao agente antes de deixá-lo prospectar.
Para agentes que falam por voz, em vez de texto, a página sobre agente de voz com IA no WhatsApp mostra o fluxo de áudio das ligações. Se o seu backend é Node e você quer o controle do envio no código, o SDK para Node.js chama as mesmas rotas que as ferramentas.
Os parâmetros de cada rota que vira ferramenta estão na referência da API, na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
Preciso de um servidor meu para usar o MCP da D-API?
Não. O servidor MCP roda na D-API. O seu agente, em qualquer cliente compatível com MCP por HTTP, conecta direto na URL com a sua API key.
Quanto tempo as mensagens ficam disponíveis para o poll_messages?
O buffer guarda as 200 mensagens mais recentes de cada sessão e expira uma hora depois da última mensagem recebida. Mensagem lida pelo poll sai do buffer.
O agente consegue usar uma sessão que a API key não enxerga?
Não. A fixação por ?sessionId= só restringe. Se a sessão não for acessível pela chave, o poll_messages responde erro e as ferramentas passam pela mesma autenticação da REST.
Como sei se uma ferramenta falhou?
O resultado traz o status HTTP da chamada. De 400 para cima, a resposta vem marcada como erro e com o corpo devolvido pela API em error, o que permite ao agente ler o motivo e decidir o próximo passo.
Posso usar o MCP junto com o webhook?
Pode. São canais independentes sobre as mesmas conexões. O webhook continua entregando os eventos ao seu backend enquanto o agente usa o MCP.