Перейти к основному содержанию
GOWA служит конечной точке Model Context Protocol в том же процессе, что и REST API. Любой клиент MCP, поддерживающий трансляцию HTTP, может отправлять сообщения, читать и управлять группами через него.
  • URL: http://<host>:3000<APP_BASE_PATH>/mcp (по умолчанию http://localhost:3000/mcp)
  • Включено по умолчанию. Отключите при помощи MCP_ENABLED=false или --mcp-enabled=false.
  • Stateless: нет сессионной рукопожатия для поддержания живых между звонками.
Обновление с старого релиза? Автономная команда ./whatsapp mcp и её конечная точка SSE по порту 8080 (/sse) пропали. Запустите ./whatsapp rest и указывает на клиентов /mcp. Старый одноинструмента-для операции был заменен консолидированными инструментами ниже.

Подключить клиента

/mcp сидит за Базовым Авторизом, как REST API. Отправьте заголовок Authorization плюс X-Device-Id, если у вас несколько устройств:
YWRtaW46Y2hhbmdlbWU= это base64("admin:changeme"); генерируйте ваш с помощью echo -n 'user:pass' | base64. Если установлено только одно устройство, поместите Authorization и X-Device-Id. Точный формат конфигурации зависит от клиента. Если клиент может запускать только stdio серверы, используйте мост, такой как mcp-remote.

Инструменты

GOWA раскрывает семь инструментов. Каждый принимает аргумент type (send) или action (все остальные), который выбирает операцию. Примечания к аргументам:
  • whatsapp_send всегда нужен type и phone. Медиа отправляется только по URL (image_url, video_url, audio_url, file_url, sticker_url); MCP не может загружать локальные файлы. link нужен link и caption; forward нужен message_id.
  • whatsapp_send принимает поля расписания (scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at, occurrence_limit). Управление результатами с помощью whatsapp_schedule (get, pause, resume и cancel нужно schedule_id).
  • whatsapp_message нужен phone (чат) и message_id; edit также нужен message.
  • В GOWA main после v9.9.0, whatsapp_message с помощью action: "edit" принимает media_type: "image" или media_type: "document" для замены заголовка. Сопоставьте исходный тип файла и пропустите link. Смотрите Изменить субтитры.
  • whatsapp_chat: get_messages нужен chat_jid; archive нужен chat_jid и archived.
  • whatsapp_app: login_code нужен phone.
Экспериментальные кнопки, запрос на размещение и отправка карусели доступны только через REST. интерактивные сообщения. Инструменты рассылки поддерживают поиск каналов и счетчики истории и автоматически обновляют подписку на live-обновления. Смотрите newsletters. При загрузке медиа URL-адреса используются те же проверки публичного адреса, что и REST посылает и подключается напрямую без HTTP_PROXY или HTTPS_PROXY. Загрузка локальных файлов требует REST API. Ваш клиент MCP показывает полную схему ввода каждого инструмента. Конечная точка HTTP принимает POST и DELETE. GET SSE стриминг отключен.

Выбор устройства

Каждый вызов решает свое устройство в указанном порядке:
  1. Аргумент device_id при вызове инструментов.
  2. Заголовок X-Device-Id на MCP соединении.
  3. Единственное зарегистрированное устройство, когда оно существует.
В противном случае звонок не выполняется с device identification required: set the X-Device-Id header or pass device_id. См. Multi-device.

Удаленные клиенты с OAuth

Hosted clients such as Claude custom connectors cannot add a Basic Auth header. Для них GOWA может запустить сервер авторизации OAuth 2.1 для /mcp. По умолчанию он отключен.
Требования и поведение:
  • APP_BASIC_AUTH должен быть установлен: страница авторизации подписывает пользователей с этими же учетными записями. Без нее запуск не выполняется.
  • Эмитент и ресурс должны быть публичными HTTPS URL, видимыми клиентами, а не внутренними адресами типа http://gowa:3000.
  • С OAuth /mcp принимает токен Марера или Базовая Авто. Жетоны не принимаются на маршрутах REST или UI.
  • Клиенты регистрируются (динамическая регистрация клиентов) с использованием RFC 7591, регистрационные органы ограничены 16 киБ и перенаправляют URI на 2 киБ. Регистрация ограничена 40 в час и 1000 неиспользованных клиентов после 24 часов.
  • Использование PKCE S256 обязательно. Срок действия кодов — 5 минут, токенов доступа — 1 час; токены обновления ротируются, а повторное использование старого токена отзывает всё семейство токенов. В MCP_OAUTH_DB_URI (по умолчанию file:storages/oauth.db) хранятся только SHA-256-хеши токенов.
URI перенаправления должны точно совпадать с зарегистрированными значениями. Нативные клиенты могут использовать HTTP-адреса обратного вызова с IP-адресом петлевого интерфейса и динамическим портом. Адреса обратного вызова с localhost требуют явно указанного порта и точного совпадения. Для остальных перенаправлений требуется HTTPS. Параметр OAuth resource привязан к каноническому URL MCP; в запросах токенов его можно опустить, но указанное значение должно совпадать. Успешные ответы авторизации содержат iss. Устаревшие коды и токены обрабатываются во время записи OAuth. Повернутые хэши refresh-token сохраняются и необходимы для обнаружения перебоев с живой семьей, в течение почти одного последующего времени жизни до 30 дней. Удаление или замена базы данных OAuth лишает права существующих клиентов и грантов. Конечные точки, относительно издателя: /oauth/authorize, /oauth/token, /oauth/register. Обнаруженные метаданные используют известные URL в корне домена, поэтому с APP_BASE_PATH=/gowa ваш прокси должен маршрутизировать:
Проверить обнаружение снаружи:
Затем добавьте https://gowa.example.com/mcp в качестве пользовательского коннектора и войдите в аккаунт APP_BASIC_AUTH.
Убедитесь, что Cloudflare Access, боты или прокси авторизации перед GOWA не могут перехватывать известные пути /oauth/* или /mcp. Ограничение неудачных входов на /oauth/authorize на вашем прокси.