🏠 Главная › User Guide › wecom callback

sidebar_position: 15 lang: ru

Обратный вызов WeCom (собственное приложение)

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

ℹ️ Info

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

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

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

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

Настройка

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

  1. Перейдите в Консоль администратора WeCom → Приложения → Создать приложение.
  2. Запишите свой Корпоративный идентификатор (отображается в верхней части консоли администратора).
  3. В настройках приложения создайте Корпоративную тайну.
  4. Обратите внимание на Идентификатор агента на странице обзора приложения.
  5. В разделе Получение сообщений настройте URL-адрес обратного вызова:
  6. URL-адрес: http://YOUR_PUBLIC_IP:8645/wecom/callback
  7. Token: Generate a random token (WeCom provides one)
  8. EncodingAESKey: Generate a key (WeCom provides one)

2. Configure Environment Variables

Add to your .env file:

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. Start the Gateway

hermes gateway

(Use hermesшлюз start only after hermesшлюз install has registered the systemd/launchd service.)

The callback adapter starts an HTTP server on the configured port. WeCom will verify the callback URL via a GET request, then begin sending messages via POST.

Configuration Reference

Set these in config.yaml under platforms.wecom_callback.extra, or use environment variables:

Setting Default Description
corp_id — WeCom enterprise Corp ID (required)
corp_se cret — Corp secret for the self-built app (required)
agent_id — Agent ID of the self-built app (required)
token — Callback verification token (required)
encoding_aes_key — 43-character AES key for callback encryption (required)
host 0.0.0.0@@IC0015@ @port 8645
path /wecom/callback URL path for the callback endpoint

Multi-App Routing

For enterprises running multiple self-built apps (e.g., across different departments or subsidiaries), configure the apps list in config.yaml@@IC0021@ @corp_id:user_id to prevent cross-corp collisions. When a user sends a message, the adapter records which app (corp) they belong to and routes replies through the correct app's access token.

Access Control

Restrict which users can interact with the app:

# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true

Endpoints

The adapter exposes:

Method Path Purpose
GET /wecom/callback URL verification handshake (WeCom sends this during setup)
POST /wecom/callback Encrypted message callback (WeCom sends user messages here)
GET /health Health check — returns {"статус": "ок"}

Шифрование

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

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

Ограничения