Crie um agente de WhatsApp com o Vercel AI SDK

Como recebe o route handler as mensagens do WhatsApp?

Com dois métodos na mesma rota, definida como destino do webhook do número, com um segredo aleatório longo 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 através de um helper de JSON é o erro clássico: o corpo chega com aspas à volta e a Meta nunca começa a entregar.

O POST recebe os eventos. Devolva 200 rapidamente e faça a chamada ao modelo depois, porque a Meta volta a tentar quando a resposta é lenta, e um arranque a frio que execute o modelo no próprio pedido pode responder duas vezes à mesma mensagem. Nas plataformas que terminam a função quando a resposta é enviada, passe o trabalho para uma fila ou para o mecanismo da plataforma para trabalho posterior à resposta.

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

Como carrega o AI SDK as ferramentas do WhatsApp?

Com o createMCPClient de @ai-sdk/mcp e o transporte HTTP, que a documentação do AI SDK recomenda para produção. O transporte recebe o URL do servidor e um authProvider, e é através do OAuth com authProvider que o servidor MCP da EasyCoexistence é autorizado: publica os metadados OAuth, suporta registo dinâmico de clientes e PKCE, e emite os seus próprios tokens após um início de sessão. Não há nenhuma chave de API para colocar num cabeçalho.

As ferramentas do cliente passam diretamente para o generateText ou o streamText. O modelo passa então a ver list_numbers, send_message, send_template, get_number_health e as restantes, com descrições que indicam a janela de 24 horas. Feche o cliente quando a chamada terminar, no callback onEnd num stream ou num bloco finally nos outros casos, como pede a documentação do AI SDK.

Use-o quando for o modelo a decidir. Para responder à mensagem que acabou de chegar, uma chamada direta à Cloud API a partir do handler é 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 por o número estar em Coexistence?

Duas coisas que o código deve ter em conta. Primeiro, pode já haver uma pessoa na conversa. A app WhatsApp Business continua a funcionar no número, e cada resposta escrita no telemóvel chega à rota como um evento echo. Um handler que, após um echo, põe o modelo em pausa para esse contacto evita que este responda por cima de uma pessoa.

Segundo, o envio está limitado a 20 mensagens por segundo, um valor fixo para o número. Um agente conversacional nunca chega perto disso, mas um ciclo de difusão escrito com Promise.all sobre uma lista de contactos chega, por isso envie em lotes.

Tudo o resto é a Cloud API normal. Nas 24 horas seguintes à última mensagem do cliente, o 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 à volta fazem falhar a verificação da Meta.
• Executar o generateText antes de responder à Meta. Num arranque a frio, a nova tentativa produz uma segunda resposta.
• Esquecer-se de fechar o cliente MCP. Cada pedido deixa uma ligação aberta até a plataforma a terminar.

Perguntas frequentes

Continue a ler