Режим обратного вызова WeCom — Пользовательские приложения

Представьте, что вы настраиваете выделенный офисный почтовый ящик для вашего ИИ-ассистента — вместо того, чтобы он прятался в групповых чатах, вы даёте ему собственный стол, к которому люди могут подходить и оставлять сообщения напрямую.

В чём главное отличие?

Hermes Agent предлагает два способа подключения WeCom (корпоративного WeChat). Режим бота — это как дружелюбный ассистент, который заходит в групповые чаты: быстро настраивается, но ограничен в возможностях. Callback-режим — другое дело: вы создаёте собственное приложение, которое появляется в боковой панели WeCom у ваших сотрудников, как любое официальное приложение. Оно выглядит как родное, поддерживает несколько компаний и безопасно обрабатывает зашифрованные сообщения.

В чём компромисс? Вам понадобится публичный сервер для приёма сообщений. Но не переживайте — для тестирования вполне подойдёт простой туннель вроде ngrok.

Как это работает на самом деле

Вот весь процесс простыми словами:

Кто-то отправляет сообщение вашему приложению в WeCom.
WeCom шифрует это сообщение и отправляет его на HTTP-эндпоинт вашего сервера.
Hermes расшифровывает его, ставит в очередь для ИИ-агента и сразу же отвечает WeCom «получил» (молча — пользователь пока ничего не видит).
Агент думает от 3 до 30 минут (в зависимости от задачи).
Hermes отправляет ответ обратно в инициативном порядке, используя API сообщений WeCom.

Никакого опроса. Никаких задержек. Просто чистый, асинхронный диалог.

Пошаговая настройка

1. Создайте приложение в админ-консоли WeCom

Войдите в админ-консоль WeCom, перейдите в раздел Приложения → Создать приложение.
Запишите ваш Corp ID (вверху консоли) и создайте Corp Secret.
На странице обзора приложения возьмите Agent ID.

В разделе Получение сообщений настройте:

URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
Token: сгенерируйте случайный
EncodingAESKey: сгенерируйте ключ из 43 символов

2. Задайте переменные окружения

Добавьте их в ваш файл .env:

WECOM_CALLBACK_CORP_ID = your-corp-id
WECOM_CALLBACK_CORP_SECRET = your-corp-secret
WECOM_CALLBACK_AGENT_ID = 1000002
WECOM_CALLBACK_TOKEN = your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY = your-43-char-aes-key

# Необязательно
WECOM_CALLBACK_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = user1,user2

3. Запустите шлюз

hermes gateway

Примечание: Используйте hermes gateway start только после того, как выполните hermes gateway install для регистрации службы.

Callback-адаптер запускает HTTP-сервер на порту 8645. WeCom проверит URL через GET-запрос, а затем начнёт отправлять сообщения через POST.

Справочник по конфигурации

Вы также можете задать эти параметры в config.yaml в разделе platforms.wecom_callback.extra:

Параметр	По умолчанию	Описание
`corp_id`	—	Обязательно. Ваш Corp ID в WeCom
`corp_secret`	—	Обязательно. Секрет приложения
`agent_id`	—	Обязательно. Agent ID вашего приложения
`token`	—	Обязательно. Токен проверки callback
`encoding_aes_key`	—	Обязательно. AES-ключ из 43 символов
`host`	не задан (dual-stack)	Адрес привязки для HTTP-сервера
`port`	8645	Порт для callback-сервера

Подводим итоги

Callback-режим WeCom — это «официальный» способ интеграции Hermes в ваш корпоративный рабочий процесс. Настройка требует больше усилий, чем бот, но результат — это отполированный, первоклассный опыт использования приложения для ваших пользователей.

Практический совет: Начните с ngrok, прежде чем открывать доступ к реальному серверу. Запустите ngrok http 8645, используйте этот URL в консоли WeCom и протестируйте с одним пользователем. Как только всё заработает, переключайтесь на production-сервер и ограничьте WECOM_CALLBACK_ALLOWED_USERS вашей командой. Удачной разработки!