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

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

WeCom Bot vs WeCom Callback

VibeOS поддерживает два режима интеграции с WeCom:

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

См. также: WeCom Bot для интеграции в стиле бота.

Выполните vibeos gateway setup и выберите WeCom Callback для пошаговой настройки.

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

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

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

• Корпоративная учетная запись 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:

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. Запустите шлюз

vibeos gateway

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

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

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

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

Параметр	По умолчанию	Описание
corp_id	—	Corp ID предприятия WeCom (обязательно)
corp_secret	—	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:

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

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

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

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

Шифрование

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

• Входящие: Расшифровка XML-полезных данных, проверка подписи SHA1
• Исходящие: Ответы отправляются через проактивный API (не зашифрованный ответ обратного вызова)

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

Ограничения

• Нет потоковой передачи — ответы приходят как полные сообщения после завершения работы агента
• Нет индикаторов набора текста — модель обратного вызова не поддерживает статус набора текста
• Только текст — в настоящее время поддерживает текстовые сообщения для ввода; ввод изображений/файлов/голоса еще не реализован. Агент знает о возможностях исходящих медиа через подсказку платформы WeCom (изображения, документы, видео, голос).
• Задержка ответа — сеансы агента занимают 3–30 минут; пользователи видят ответ, когда обработка завершена

Устранение неполадок

Ошибка проверки подписи. WeCom подписывает каждый запрос токеном, который вы зарегистрировали в консоли администратора. Несоответствие между токеном, настроенным в VibeOS, и токеном, который ожидает консоль администратора, является наиболее частой причиной. Скопируйте заново и токен, и EncodingAESKey из консоли администратора — их легко обрезать. Пробелы в значениях ~/.vibeos/.env вокруг = также нарушат проверку подписи. После исправления перезапустите vibeos gateway run.

URL обратного вызова недоступен / этап проверки не удается. WeCom обращается к публичному URL, который вы зарегистрировали. Убедитесь:

1. Ваш обратный прокси / туннель перенаправляет /wecom/callback на порт шлюза.
2. URL в консоли администратора использует HTTPS (WeCom отклоняет обычный HTTP).
3. Извне вашей сети curl -i https://<ваш-домен>/wecom/callback возвращает что-то отличное от тайм-аута (4xx без параметров запроса — это нормально, это просто означает, что слушатель доступен).

Порт недоступен / слушатель не привязан. Проверьте логи vibeos gateway run на предмет привязанного хоста/порта. Если адаптер привязался к 127.0.0.1, вы должны разместить перед ним обратный прокси или туннель — серверы WeCom не могут достичь loopback. Установите extra.host: 0.0.0.0 в config.yaml (плюс allowed_source_cidrs, если вы открываете прямой доступ) или оставьте loopback и используйте туннель, например Cloudflare Tunnel / nginx.