🏠 Главная › Документация › Мессенджеры

WeCom Callback (собственное приложение)

Подключение Hermes к WeCom (корпоративный WeChat) как собственного корпоративного приложения с использованием модели callback/webhook.

info WeCom Bot vs WeCom Callback Hermes поддерживает два режима интеграции с WeCom:

Как это работает

  1. Вы регистрируете собственное приложение в консоли администратора WeCom

  2. WeCom отправляет зашифрованный XML на ваш HTTP-callback-эндпоинт

  3. Hermes расшифровывает сообщение, ставит его в очередь для агента

  4. Немедленно подтверждает (беззвучно — пользователю ничего не отображается)

  5. Агент обрабатывает запрос (обычно 3–30 минут)

  6. Ответ доставляется проактивно через WeCom API message/send

Предварительные требования

Настройка

1. Создание собственного приложения в WeCom

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

  2. Запишите ваш Corp ID (отображается вверху консоли администратора)

  3. В настройках приложения создайте Corp Secret

  4. Запишите Agent ID со страницы обзора приложения

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

  6. URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
  7. Token: Сгенерируйте случайный токен (WeCom предоставляет его)
  8. EncodingAESKey: Сгенерируйте ключ (WeCom предоставляет его)

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

# Optional
WECOM_CALLBACK_HOST=0.0.0.0
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

3. Запуск Gateway

hermes gateway

(Используйте hermes gateway start только после того, как hermes gateway install зарегистрировал службу systemd/launchd.)

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

Справочник по настройке

Установите их в config.yaml в разделе platforms.wecom_callback.extra или используйте переменные окружения:

Параметр По умолчанию Описание
corp_id — Corp ID предприятия WeCom (обязательно)
corp_secret — Corp secret для собственного приложения (обязательно)
agent_id — Agent ID собственного приложения (обязательно)
token — Токен подтверждения callback (обязательно)
encoding_aes_key — 43-символьный AES-ключ для шифрования callback (обязательно)
host 0.0.0.0 Адрес привязки для HTTP-сервера callback
port 8645 Порт для HTTP-сервера callback
path /wecom/callback URL-путь для конечной точки callback

Маршрутизация нескольких приложений

Для предприятий, использующих несколько собственных приложений (например, в разных отделах или дочерних компаниях), настройте список apps в config.yaml:

platforms:
  wecom_callback:
    enabled: true
    extra:
      host: "0.0.0.0"
      port: 8645
      apps:
        - name: "dept-a"
          corp_id: "ww_corp_a"
          corp_secret: "secret-a"
          agent_id: "1000002"
          token: "token-a"
          encoding_aes_key: "key-a-43-chars..."
        - name: "dept-b"
          corp_id: "ww_corp_b"
          corp_secret: "secret-b"
          agent_id: "1000003"
          token: "token-b"
          encoding_aes_key: "key-b-43-chars..."

Пользователи ограничены по corp_id:user_id для предотвращения конфликтов между корпорациями. Когда пользователь отправляет сообщение, адаптер записывает, к какому приложению (корпорации) он принадлежит, и маршрутизирует ответы через правильный токен доступа приложения.

Контроль доступа

Ограничьте, какие пользователи могут взаимодействовать с приложением:

# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true

Конечные точки

Адаптер предоставляет:

Метод Путь Назначение
GET /wecom/callback Подтверждение URL (WeCom отправляет это при настройке)
POST /wecom/callback Зашифрованный callback сообщения (WeCom отправляет сюда сообщения пользователей)
GET /health Проверка состояния — возвращает {"status": "ok"}

Шифрование

Все полезные нагрузки callback зашифрованы с помощью AES-CBC с использованием EncodingAESKey. Адаптер обрабатывает:

Криптографическая реализация совместима с официальным SDK WXBizMsgCrypt от Tencent.

Ограничения