🏠 Главная › user guide › wecom callback

WeCom Callback (самостоятельно созданное приложение)

Подключите Hermes к WeCom (Enterprise WeChat) в качестве самостоятельно созданного внутреннего приложения, с помощью модели обратного вызова/вебхука.

ℹ️ Info

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

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

  1. Вы регистрируете самостоятельно созданное приложение в консоли администратора WeCom.
  2. WeCom отправляет зашифрованный XML на вашу конечную точку обратного вызова HTTP.
  3. Гермес расшифровывает сообщение, показывая его очередь агенту.
  4. Немедленное подтверждение получения (молча — ничего не отображается пользователю)
  5. Агент обрабатывает запрос (обычно 3–30 минут).
  6. Ответ доставляется проактивно через API message/send WeCom.

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

Настройка

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

  1. Перейдите в Консоль администратора WeCom → Приложения → Создать приложение
  2. Запишите свой Корпоративный идентификатор (отображается вверху консоли администратора)
  3. В приложении приложения создайте Корпоративную тайну.
  4. Запишите ID агента на страницу обзора приложения.
  5. В разделе Прием сообщений настройте обратный вызов URL:
  6. URL: http://ВАШ_ПУБЛИЧНЫЙ_IP:8645/wecom/callback
  7. Токен: сгенерируйте случайный токен (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

# Опционально
WECOM_CALLBACK_HOST=0.0.0.0
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

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

hermes gateway

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

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

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

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

Настройка По умолчанию Описание
corp_id — WeCom Corp ID организации (обязательно)
corp_secret — Секрет организации для самостоятельно созданного приложения (обязательно)
агент_ид — ID агента самостоятельно созданного приложения (обязательно)
жетон — Токен проверяет обратный звонок (обязательно)
encoding_aes_key — 43-символьный AES-ключ для обратного вызова шифрования (обязательно)
хозяин 0.0.0.0 Адрес привязки для обратного вызова HTTP-сервера
порт 8645 Порт для обратного вызова HTTP-сервера
путь /wecom/обратный вызов Путь URL для обратного вызова конечной точки

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

Для предприятий, использующих несколько самостоятельно созданных приложений (например, в разных подразделениях или дочерних компаниях), настройте список приложений в файле 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, чтобы предотвратить коллизию между организациями. Когда пользователь отправляет сообщение, адаптер записывает, к какому приложению (организации) он принадлежит, и направляет ответы через соответствующий токен доступа приложения.

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

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

# Белый список конкретных пользователей
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Или разрешить всех пользователей
WECOM_CALLBACK_ALLOW_ALL_USERS=true

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

Адаптер обеспечивает:

Метод Путь Назначение
ПОЛУЧИТЬ /wecom/обратный вызов URL-адрес проверки (WeCom отправляет его во время настройки)
ПОСТ /wecom/обратный вызов Зашифрованные сообщения обратного вызова (WeCom отправляет сюда сообщения пользователей)
ПОЛУЧИТЬ /здоровье Проверка работоспособности — возвращает {"status": "ok"}

Шифирование

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

Реализация криптографии совместима с возможностью SDK WXBizMsgCrypt от Tencent.

Ограничения