Crea un agente de WhatsApp con el Vercel AI SDK

¿Cómo recibe el route handler los mensajes de WhatsApp?

Con dos métodos en una misma ruta, configurada como destino del webhook del número y con un secreto largo y aleatorio en la ruta.

El GET responde a la verificación de Meta. Lee hub.mode, hub.verify_token y hub.challenge de la query, compara el token y devuelve el challenge como texto plano. Devolverlo con un helper de JSON es el error clásico: el cuerpo llega entre comillas y Meta nunca empieza a entregar.

El POST recibe los eventos. Devuelve 200 enseguida y llama al modelo después, porque Meta reintenta las respuestas lentas y un arranque en frío que ejecute el modelo en línea puede responder dos veces al mismo mensaje. En plataformas que terminan la función al enviar la respuesta, pasa el trabajo a una cola o al mecanismo de la plataforma para tareas posteriores a la respuesta.

El secreto de la ruta es la autenticación. Meta firma cada entrega con el app secret del Tech Provider, así que la cabecera X-Hub-Signature-256 no se puede comprobar de tu lado.

¿Cómo carga el AI SDK las herramientas de WhatsApp?

Con createMCPClient de @ai-sdk/mcp y el transporte HTTP, que la documentación del AI SDK recomienda para producción. El transporte recibe la URL del servidor y un authProvider, y OAuth mediante un authProvider es como se autoriza el servidor MCP de EasyCoexistence: publica metadatos OAuth, admite registro dinámico de clientes y PKCE, y emite sus propios tokens tras iniciar sesión. No hay ninguna clave de API que poner en una cabecera.

Las herramientas del cliente se pasan directamente a generateText o streamText. Así el modelo ve list_numbers, send_message, send_template, get_number_health y las demás, con descripciones que indican la ventana de 24 horas. Cierra el cliente al terminar la llamada, en el callback onEnd si es un stream o en un bloque finally en los demás casos, como pide la documentación del AI SDK.

Úsalo cuando el modelo deba decidir. Para responder al mensaje que acaba de llegar, una llamada directa a la Cloud API desde el handler es más corta.

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();
}

¿Qué cambia porque el número está en Coexistencia?

Dos cosas que el código debe tener en cuenta. Primero, puede que una persona ya esté en la conversación. La app de WhatsApp Business sigue funcionando en el número, y cada respuesta escrita en el teléfono llega a la ruta como un evento echo. Un handler que pausa el modelo para un contacto después de un echo evita que conteste por encima de una persona.

Segundo, el envío tiene un tope fijo de 20 mensajes por segundo para el número. Un agente conversacional nunca se acerca a ese límite, pero un bucle de difusión escrito con Promise.all sobre una lista de contactos sí, así que envíalo por lotes.

Todo lo demás es la Cloud API de siempre. Dentro de las 24 horas posteriores al último mensaje del cliente se permite texto libre. Pasado ese plazo, solo se entrega una plantilla aprobada, y el texto libre devuelve el error 131047 sin que el cliente vea nada.

Errores comunes

• Devolver el challenge con un helper de respuesta JSON. Las comillas que lo rodean hacen fallar la comprobación de Meta.
• Ejecutar generateText antes de responder a Meta. En un arranque en frío, el reintento produce una segunda respuesta.
• Olvidar cerrar el cliente MCP. Cada petición deja una conexión abierta hasta que la plataforma la corta.

Preguntas frecuentes

Sigue leyendo