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

WeCom (корпоративный WeChat)

Подключите Hermes к WeCom (企业微信), корпоративной платформе обмена сообщениями Tencent. Адаптер использует шлюз WeCom AI Bot WebSocket для двунаправленной связи в первое время — не требуется общедоступная конечная точка или веб-перехватчик.

См. также: WeCom Callback для настройки входящего веб-перехватчика.

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

Настройка

Шаг 1. Создание ИИ-бота

рекомендуется: сканирование и создание (одна команда)

hermes gateway setup

Выберите WeCom и отсканируйте QR-код с помощью местного приложения WeCom. Hermes автоматически создает бот-приложение с указанными разрешениями и сохраняет учетные данные.

Мастер установки выполнит следующие действия: 1. Отобразите QR-код в своем терминале. 2. Подождите, пока отсканируете его с помощью местного приложения WeCom. 3. Автоматически получить идентификатор и секрет бота. 4. Проведет вас через уровень контроля доступа.

Альтернатива: ручная настройка

Если датчик для изготовления недоступен, мастер возвращается к ручному вводу:

  1. Войдите в консоль администратора WeCom.
  2. Перейдите к Приложения → Создать приложение → AI Bot.
  3. Укажите имя и описание бота.
  4. Скопируйте Идентификатор бота и Секрет на странице учетных данных.
  5. Запустите программу настройки шлюза Hermes, выберите WeCom и введите учетные данные при получении запроса.:::предупреждение. Держите секрет бота в тайне. Любой, у кого он есть, может выдать себя за вашу боту.

Шаг 2. Настраиваем Гермес

Вариант A: Интерактивная настройка (рекомендуется)

hermes gateway setup

Выберите WeCom и следуйте за людьми. Мастер проведет вас через: - Учетные данные бота (через QR-сканирование или ввод вручную) - Настройки контроля доступа (белый список, режим подключения или открытый доступ) - Домашний канал для подтверждения

Вариант Б: Настройка вручную

Добавьте следующее в ~/.hermes/.env:

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret

# Optional: restrict access
WECOM_ALLOWED_USERS=user_id_1,user_id_2

# Optional: home channel for cron/notifications
WECOM_HOME_CHANNEL=chat_id

Шаг 3: Запустите шлюз

hermes gateway

Особенности

Параметры конфигурации

Установите их в config.yaml в platforms.wecom.extra:

Ключ По умолчанию Описание
bot_id — Идентификатор бота WeCom AI (обязательно)
секрет — Секрет WeCom AI Bot (обязательно)
websocket_url wss://openws.work.weixin.qq.com URL-адрес шлюза WebSocket
dm_policy открытый Доступ в ДМ: «открытый», «белый список», «отключен», «сопряжение»
group_policy открытый Групповой доступ: «открытый», «белый список», «отключенный»
allow_from [] Идентификаторы пользователей, разрешенные для личных сообщений (когда dm_policy=allowlist)
group_allow_from [] Идентификаторы групп разрешены (когда group_policy=allowlist)
группы {} Групповая часть (см. ниже)

Политики доступа

Политика в Директ

Определяет, кто может отправлять прямые сообщения боту:

Значение Поведение
открытый Любой может отправить сообщение боту (по умолчанию)
белый список Только идентификаторы пользователей в allow_from могут отправлять сообщения
инвалид Все в DM теряются
спаривание Режим подключения (для первоначальной настройки) 
WECOM_DM_POLICY=allowlist

Групповая политика

Определяет, в каких группах отвечает бот:

Значение Поведение
открытый Бот отвечает во всех группах (по умолчанию)
белый список Бот отвечает только на группы с идентификаторами, запросы в group_allow_from
инвалид Все групповые сообщения игнорируются 
WECOM_GROUP_POLICY=allowlist

Белые надежные отправители для каждой группы

Для детального контроля вы можете проверить, каким пользователям разрешено взаимодействовать с ботом в определенных группах. Это вред в config.yaml:

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "your-bot-id"
      secret: "your-secret"
      group_policy: "allowlist"
      group_allow_from:
        - "group_id_1"
        - "group_id_2"
      groups:
        group_id_1:
          allow_from:
            - "user_alice"
            - "user_bob"
        group_id_2:
          allow_from:
            - "user_charlie"
        "*":
          allow_from:
            - "user_admin"

How it works:

  1. The group_policy and group_allow_from controls determine whether a group is allowed at all.
  2. If a group passes the top-level check, the groups.<group_id>.allow_from list (if present) further restricts which senders within that group can interact with the bot.
  3. A wildcard "*" group entry serves as a default for groups not explicitly listed.
  4. Allowlist entries support the * wildcard to allow all users, and entries are case-insensitive.
  5. Entries can optionally use the wecom:user: or wecom:group: prefix format — the prefix is stripped automatically.

If no allow_from is configured for a group, all users in that group are allowed (assuming the group itself passes the top-level policy check).

Media Support

Inbound (receiving)

The adapter receives media attachments from users and caches them locally for agent processing:

Type How it's handled
Images Downloaded and cached locally. Supports both URL-based and base64-encoded images.
Files Downloaded and cached. Filename is preserved from the original message.
Voice Voice message text transcription is extracted if available.
Mixed messages WeCom mixed-type messages (text + images) are parsed and all components extracted.

Quoted messages: Media from quoted (replied-to) messages is also extracted, so the agent has context about what the user is replying to.

AES-Encrypted Media Decryption

WeCom encrypts some inbound media attachments with AES-256-CBC. The adapter handles this automatically:

No configuration is needed — decryption happens transparently when encrypted media is received.

Outbound (sending)

Method What it sends Size limit
send Markdown text messages 4000 chars
send_image / send_image_file Native image messages 10 MB
send_document File attachments 20 MB
send_voice Voice messages (AMR format only for native voice) 2 MB
send_video Video messages 10 MB

Chunked upload: Files are uploaded in 512 KB chunks through a three-step protocol (init → chunks → finish). The adapter handles this automatically.

Automatic downgrade: When media exceeds the native type's size limit but is under the absolute 20 MB file limit, it is automatically sent as a generic file attachment instead:

Files exceeding the absolute 20 MB limit are rejected with an informational message sent to the chat.

Reply-Mode Responses

When the bot receives a message via the WeCom callback, the adapter remembers the inbound request ID. If a response is sent while the request context is still active, the adapter uses WeCom's reply-mode (aibot_respond_msg) to correlate the response directly to the inbound message. This provides a more natural conversation experience in the WeCom client.

The full response is delivered as a single message — the adapter does not stream tokens incrementally. If the inbound request context has expired or is unavailable, the adapter falls back to proactive message sending via aibot_send_msg.

Reply-mode also works for media: uploaded media can be sent as a reply to the originating message.

Connection and Reconnection

The adapter maintains a persistent WebSocket connection to WeCom's gateway at wss://openws.work.weixin.qq.com.

Connection Lifecycle

  1. Connect: Opens a WebSocket connection and sends an aibot_subscribe authentication frame with the bot_id and secret.
  2. Heartbeat: Sends application-level ping frames every 30 seconds to keep the connection alive.
  3. Listen: Continuously reads inbound frames and dispatches message callbacks.

Reconnection Behavior

On connection loss, the adapter uses exponential backoff to reconnect:

Attempt Delay
1st retry 2 seconds
2nd retry 5 seconds
3rd retry 10 seconds
4th retry 30 seconds
5th+ retry 60 seconds

After each successful reconnection, the backoff counter resets to zero. All pending request futures are failed on disconnect so callers don't hang indefinitely.

Deduplication

Inbound messages are deduplicated using message IDs with a 5-minute window and a maximum cache of 1000 entries. This prevents double-processing of messages during reconnection or network hiccups.

All Environment Variables

Variable Required Default Description
WECOM_BOT_ID ✅ — WeCom AI Bot ID
WECOM_SECRET ✅ — WeCom AI Bot Secret
WECOM_ALLOWED_USERS — (empty) Comma-separated user IDs for the gateway-level allowlist
WECOM_HOME_CHANNEL — — Chat ID for cron/notification output
WECOM_WEBSOCKET_URL — wss://openws.work.weixin.qq.com WebSocket gateway URL
WECOM_DM_POLICY — open DM access policy
WECOM_GROUP_POLICY — open Group access policy

Troubleshooting

Problem Fix
WECOM_BOT_ID and WECOM_SECRET are required Set both env vars or configure in setup wizard
WeCom startup failed: aiohttp not installed Install aiohttp: pip install aiohttp
WeCom startup failed: httpx not installed Install httpx: pip install httpx
invalid secret (errcode=40013) Verify the secret matches your bot's credentials
Timed out waiting for subscribe acknowledgement Check network connectivity to openws.work.weixin.qq.com
Bot doesn't respond in groups Check group_policy setting and ensure the group ID is in group_allow_from
Bot ignores certain users in a group Check per-group allow_from lists in the groups config section
Media decryption fails Install cryptography: pip install cryptography
cryptography is required for WeCom media decryption The inbound media is AES-encrypted. Install: pip install cryptography
Voice messages sent as files WeCom only supports AMR format for native voice. Other formats are auto-downgraded to file.
File too large error WeCom has a 20 MB absolute limit on all file uploads. Compress or split the file.
Images sent as files Images > 10 MB exceed the native image limit and are auto-downgraded to file attachments.
Timeout sending message to WeCom The WebSocket may have disconnected. Check logs for reconnection messages.
WeCom websocket closed during authentication Network issue or incorrect credentials. Verify bot_id and secret.