Документация по возможностям платформы WeCom (WeChat Work)

WeComAdapter — это адаптер, построенный на основе API самостоятельного приложения (self-built app) WeCom, который принимает сообщения через колбэки, активно отправляет их через интерфейс сообщений приложения, а также предоставляет возможности корпоративной адресной книги и карточек сообщений.

Информация о документе

Версия соответствующего модуля: 0.1.0
Сопровождающий: ErisPulse

Основная информация

Краткое описание платформы: бот на основе самостоятельного приложения WeCom, подходит для внутренних корпоративных уведомлений, интеллектуальных вопросов и ответов, офисной автоматизации и других сценариев
Название адаптера: WeComAdapter
Поддержка нескольких аккаунтов: поддерживается одновременная настройка нескольких предприятий (каждый аккаунт соответствует одному corpid + приложению)
Способ подключения: приём HTTP-колбэков (URL приёма сообщений настраивается в административной панели WeCom) + активная отправка через API
Способ аутентификации: обмен corpid + secret на access_token (автоматическое обновление)
Шифрование колбэков: Token + EncodingAESKey (официальный протокол шифрования/дешифрования WeCom)
Поддержка цепочечных методов: поддержка цепочечных методов модификации, таких как .Reply()
Совместимость с OneBot12: отправка поддерживает стандартные сегменты сообщений OneBot12

Описание конфигурации

# config.toml
[WeComAdapter.accounts.default]
corpid = "YOUR_CORP_ID"        # ID компании (обязательно, админ-панель WeCom — «Моя компания»)
secret = "YOUR_APP_SECRET"     # Secret приложения (обязательно, страница деталей собственного приложения)
agentid = 1000002              # AgentId приложения (обязательно, страница деталей собственного приложения)
callback_enabled = true        # Включить приём callback (по умолчанию true; при отключении доступна только активная отправка)
token = "YOUR_CALLBACK_TOKEN"  # Token проверки callback (настройка приёма сообщений в админ-панели WeCom)
encoding_aes_key = "YOUR_AES_KEY_43CHARS"  # Ключ шифрования/дешифрования callback (43 символа)
callback_path = "/wecom/{account}"         # Путь callback, поддерживает плейсхолдер {account}
enabled = true

Описание параметров конфигурации (для каждой учётной записи):

corpid / secret / agentid: получаются на странице собственного приложения в админ-панели WeCom (первые два параметра обязательны)
callback_enabled: переключатель приёма callback (по умолчанию включён). При отключении адаптер пропускает регистрацию маршрута callback и сохраняет только возможность активной отправки; связанные с callback поля в панели соответственно скрываются
token / encoding_aes_key: проверка и шифрование/дешифрование callback-сообщений, должны совпадать с настройкой «Приём сообщений» в админ-панели WeCom
callback_path: путь приёма callback (по умолчанию /wecom/{имя_аккаунта}), в админ-панели WeCom необходимо указать полный URL: http(s)://ваш-адрес:порт/wecom/<имя_аккаунта>

Предварительные условия для приёма сообщений: админ-панель WeCom → собственное приложение → в настройке «Приём сообщений» включите приём через API, в поле URL укажите полный callback-адрес, приведённый выше, Token и EncodingAESKey должны совпадать с конфигурацией. Внимание: WeCom требует, чтобы callback URL был доступен из интернета (рекомендуется использовать обратный прокси).

API-окружение:

Базовый адрес API: https://qyapi.weixin.qq.com/cgi-bin
access_token автоматически получается и обновляется в кэше, ручное управление не требуется

Отправка сообщений

from ErisPulse import sdk
wecom = sdk.adapter.get("wecom")

# Базовые сообщения (target_type: "user"=участник, "group"=групповой чат приложения)
await wecom.Send.To("user", "zhangsan").Text("Привет")
await wecom.Send.To("group", "group_chat_id").Markdown("**Жирное** уведомление")

# Медиа (локальный путь / bytes / URL; автоматическая загрузка временного медиафайла, затем отправка)
await wecom.Send.To("user", "zhangsan").Image("banner.png")
await wecom.Send.To("user", "zhangsan").Voice("voice.amr")
await wecom.Send.To("user", "zhangsan").Video("demo.mp4")
await wecom.Send.To("user", "zhangsan").File("report.pdf")

# Новости и карточки
await wecom.Send.To("user", "zhangsan").News([
    {"title": "Заголовок", "description": "Аннотация", "url": "https://...", "picurl": "https://.../img.png"},
])  # не более 8 элементов

await wecom.Send.To("user", "zhangsan").TextCard(
    title="Напоминание об утверждении",
    description="У вас есть документ, ожидающий утверждения",
    url="https://oa.example.com/approval/1",
    btntxt="Обработать",
)

await wecom.Send.To("user", "zhangsan").TemplateCard(
    card_type="text_notice",  # тип карточки WeCom, остальные параметры передаются напрямую как JSON карточки согласно официальному формату
    source={"icon_url": "...", "desc": "OA"},
    main_title={"title": "Напоминание о встрече"},
)

# Пассивный ответ: event.reply() принятого сообщения отправляет ответ напрямую пользователю-отправителю

Стандартные действия API

info = await wecom.Api.get_self_info()          # Информация о приложении (corpid/agentid)
status = await wecom.Api.get_status()           # Статус работы
ver = await wecom.Api.get_version()             # Версия адаптера

# Адресная книга (добавлено в 2.1.0, автоматическая вставка access_token)
user = await wecom.Api.get_user_info("zhangsan")            # Детали участника (имя/отдел/должность/аватар)
depts = await wecom.Api.get_department_list(0)              # Список отделов (0=корневой отдел)
members = await wecom.Api.get_department_users(2)           # Список участников отдела
uid = await wecom.Api.get_user_by_mobile("13800000000")     # Получение userid по номеру телефона
openid = await wecom.Api.userid_to_openid("zhangsan")       # userid → openid (красные конверты/внешние платежи)
userid = await wecom.Api.openid_to_userid("oXXXX")          # openid → userid

# Несколько аккаунтов
result = await wecom.Api.Using("corp2").get_user_info("lisi")

# Прямой вызов любого API WeCom (endpoint относительно cgi-bin, access_token добавляется автоматически)
result = await wecom.Api.call("message/send", touser="zhangsan", msgtype="text", agentid=1000002, text={"content": "hi"})

Описание событий

События сообщений: detail_type принимает значение private (участник отправляет сообщение) / group (сообщения группового чата приложения); user_id — это userid участника
Объект события предоставляет расширенные методы чтения, такие как get_raw_xml() (исходный XML обратного вызова)
События отчётов (подписка, нажатие пунктов меню и т.д.) преобразуются в события типа request / notice

Важные замечания

Callback URL должен быть доступен из публичной сети: для локальной разработки можно использовать туннелирование во внутреннюю сеть; в продакшене рекомендуется обратный прокси Nginx на порт router ErisPulse
Частота активной отправки: ограничена интерфейсом сообщений приложений WeCom (корпоративного WeChat) (суточный объём на приложение зависит от масштаба организации); для массовых рассылок используйте TaskCard/TemplateCard в сочетании с тегами
Действительность access_token: адаптер обновляет его автоматически; при развертывании нескольких экземпляров с одним corpid+secret учитывайте официальное ограничение на взаимное вытеснение токенов (рекомендуется, чтобы отправка и приём выполнялись централизованно одним экземпляром)
Медиафайлы: Voice должен быть в формате AMR (ограничение WeCom); большие файлы отправляются через интерфейс временных материалов (адаптер обрабатывает это автоматически)