Создайте агента для WhatsApp на Vercel AI SDK

Как обработчик маршрута получает сообщения WhatsApp?

Двумя методами на одном маршруте, который указан как адрес вебхука для номера, с длинным случайным секретом в пути.

GET отвечает на проверку Meta. Прочитайте из запроса hub.mode, hub.verify_token и hub.challenge, сравните токен и верните challenge как простой текст. Классическая ошибка: вернуть его через JSON-помощник. Тело приходит в кавычках, и Meta не начинает доставку.

POST получает события. Быстро верните 200 и вызывайте модель уже после этого: Meta повторяет медленные ответы, а холодный старт с вызовом модели внутри запроса может ответить на одно и то же сообщение дважды. На платформах, которые завершают функцию после отправки ответа, передайте работу в очередь или в механизм платформы для работы после ответа.

Секрет в пути и есть аутентификация. Meta подписывает каждую доставку секретом приложения Tech Provider, поэтому заголовок X-Hub-Signature-256 на вашей стороне проверить нельзя.

Как AI SDK загружает инструменты WhatsApp?

Через createMCPClient из @ai-sdk/mcp и HTTP-транспорт, который документация AI SDK рекомендует для рабочей среды. Транспорт принимает URL сервера и authProvider, и именно OAuth через authProvider авторизует сервер EasyCoexistence MCP: он публикует метаданные OAuth, поддерживает динамическую регистрацию клиентов и PKCE и выдаёт собственные токены после входа. API-ключа для заголовка нет.

Инструменты клиента передаются прямо в generateText или streamText. Модель видит list_numbers, send_message, send_template, get_number_health и другие, с описаниями, где указано окно в 24 часа. Закрывайте клиент после вызова: в колбэке onEnd для потока или в блоке finally в остальных случаях, как требует документация AI SDK.

Используйте это там, где решение должна принимать модель. Чтобы ответить на только что пришедшее сообщение, короче прямой вызов Cloud API из обработчика.

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

Что меняется, если номер работает в Coexistence?

Два момента, о которых код должен знать. Во-первых, в диалоге уже может быть человек. Приложение WhatsApp Business продолжает работать на номере, и каждый ответ, набранный на телефоне, приходит на маршрут как событие echo. Обработчик, который после echo приостанавливает модель для этого контакта, не даёт ей отвечать поверх человека.

Во-вторых, отправка ограничена фиксированными 20 сообщениями в секунду для номера. Диалоговый агент до этого предела не доходит, а цикл рассылки на Promise.all по списку контактов дойдёт, поэтому разбивайте его на пакеты.

Всё остальное представляет собой обычный Cloud API. В течение 24 часов после последнего сообщения клиента разрешён свободный текст. После этого проходит только одобренный шаблон, а свободный текст возвращает ошибку 131047, и клиент ничего не видит.

Распространённые ошибки

• Возврат challenge через JSON-помощник. Кавычки вокруг него не проходят проверку Meta.
• Вызов generateText до ответа Meta. При холодном старте повторная доставка приводит ко второму ответу.
• Незакрытый клиент MCP. Каждый запрос оставляет открытое подключение, пока платформа его не завершит.

Часто задаваемые вопросы

Читайте дальше