Crie um agente de WhatsApp com o Vercel AI SDK

Como o manipulador de rota recebe as mensagens do WhatsApp?

Com dois métodos na mesma rota, definida como destino do webhook do número, com um segredo longo e aleatório no caminho.

O GET responde à verificação da Meta. Leia hub.mode, hub.verify_token e hub.challenge da query, compare o token e devolva o challenge como texto simples. Devolvê-lo por um helper de JSON é o erro clássico: o corpo chega com aspas ao redor e a Meta nunca começa a entregar.

O POST recebe os eventos. Devolva 200 rápido e chame o modelo depois, porque a Meta repete respostas lentas e uma inicialização a frio que executa o modelo na hora pode responder à mesma mensagem duas vezes. Em plataformas que encerram a função quando a resposta é enviada, passe o trabalho para uma fila ou para o mecanismo da plataforma para tarefas após a resposta.

O segredo no caminho é a autenticação. A Meta assina cada entrega com o segredo do app do Tech Provider, então o cabeçalho X-Hub-Signature-256 não pode ser verificado do seu lado.

Como o AI SDK carrega as ferramentas do WhatsApp?

Com createMCPClient de @ai-sdk/mcp e o transporte HTTP, que a documentação do AI SDK recomenda para produção. O transporte recebe a URL do servidor e um authProvider, e o OAuth por um authProvider é a forma de autorizar o servidor MCP do EasyCoexistence: ele publica os metadados de OAuth, aceita registro dinâmico de cliente e PKCE, e emite os próprios tokens após o login. Não há chave de API para colocar em um cabeçalho.

As ferramentas do cliente vão direto para generateText ou streamText. O modelo passa a ver list_numbers, send_message, send_template, get_number_health e as demais, com descrições que informam a janela de atendimento de 24 horas. Feche o cliente quando a chamada terminar, no callback onEnd em um stream ou em um bloco finally nos outros casos, como a documentação do AI SDK pede.

Use onde o modelo deve decidir. Para responder à mensagem que acabou de chegar, uma chamada direta à Cloud API a partir do manipulador é mais curta.

import { createMCPClient } from "@ai-sdk/mcp";

const mcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://easycoexistence.com/api/mcp",
    authProvider, // your OAuthClientProvider implementation
  },
});

try {
  const tools = await mcp.tools();
  // pass tools to generateText({ model, tools, prompt })
} finally {
  await mcp.close();
}

O que muda porque o número está na Coexistência?

Duas coisas que o código deve levar em conta. Primeiro, uma pessoa pode já estar na conversa. O app do WhatsApp Business continua funcionando no número, e cada resposta digitada no celular chega à rota como um evento de eco. Um manipulador que pausa o modelo para um contato depois de um eco evita responder por cima de uma pessoa.

Segundo, o envio tem um limite fixo de 20 mensagens por segundo para o número. Um agente conversacional nunca chega perto disso, mas um laço de envio em massa escrito com Promise.all sobre uma lista de contatos chega, então agrupe em lotes.

Todo o resto é a Cloud API comum. Dentro de 24 horas da última mensagem do cliente, texto livre é permitido. Depois disso, só passa um template aprovado, e o texto livre devolve o erro 131047 sem que o cliente veja nada.

Erros comuns

• Devolver o challenge com um helper de resposta JSON. As aspas ao redor fazem a verificação da Meta falhar.
• Executar generateText antes de responder à Meta. Em uma inicialização a frio, a repetição gera uma segunda resposta.
• Esquecer de fechar o cliente MCP. Cada requisição deixa uma conexão aberta até a plataforma encerrá-la.

Perguntas frequentes

Continue lendo