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

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:

  1. Qual API key. O agente terá exatamente as permissões dessa chave. As ferramentas chamam a API pela mesma autenticação da REST.
  2. 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.
  3. 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 o limit. 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_messages depende 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: true e 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.

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.