Перейти к содержанию

Callback

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

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

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

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

  • Учётная запись WeCom предприятия с правами администратора
  • Пакеты Python aiohttp и httpx (включены в стандартную установку)
  • Публично доступный сервер для URL обратного вызова (или туннель типа ngrok)

Настройка​

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

  1. Перейдите в консоль администратора WeCom → Приложения → Создать приложение
  2. Запомните ваш Corp ID (отображается в верхней части консоли администратора)
  3. В настройках приложения создайте Corp Secret
  4. Запомните Agent ID со страницы обзора приложения
  5. В разделе Получение сообщений настройте URL обратного вызова:
    • URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
    • Token: Сгенерируйте случайный токен (WeCom предоставляет его)
    • EncodingAESKey: Сгенерируйте ключ (WeCom предоставляет его)

2\. Настройка переменных окружения​

Добавьте в ваш файл .env: [code] 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

[/code]

3\. Запуск шлюза​

[code] hermes gateway

[/code] (Используйте hermes gateway start только после того, как hermes gateway install зарегистрирует службу systemd/launchd.) Адаптер обратного вызова запускает HTTP-сервер на настроенном порту. WeCom проверит URL обратного вызова через GET-запрос, после чего начнёт отправлять сообщения через POST.

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

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

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

Для предприятий, запускающих несколько самостоятельно созданных приложений (например, в разных отделах или дочерних компаниях), настройте список apps в config.yaml: [code] 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..."

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

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

Ограничьте, какие пользователи могут взаимодействовать с приложением: [code] # Белый список конкретных пользователей
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu 

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

[/code]

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

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

Шифрование​

Все полезные данные обратного вызова шифруются с помощью AES-CBC с использованием EncodingAESKey. Адаптер обрабатывает: * Входящие : Расшифровка XML-полезных данных, проверка подписи SHA1 * Исходящие : Ответы отправляются через активный API (не через зашифрованный ответ обратного вызова)

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

Ограничения​