Адаптер официального аккаунта WeChat (WechatMp) — документация по особенностям платформы
Основная информация
- Название модуля:
ErisPulse-WechatMpAdapter - Идентификатор платформы:
mp(псевдоним:wechat_mp) - Версия модуля: 4.3.2
- Сопровождающий: ErisPulse
- Последнее обновление: 2026-11-10
- Зависимости:
cryptography
Обновление парадигмы v5 (4.2.0)
- Наследование BaseConverter: общие поля конвертера формируются фреймворком через build_base_event
- Минимальный набор Api DSL: get_self_info (appid) / get_status / get_version / get_supported_actions
- Мягкая зависимость от фреймворка: во время выполнения проверяется наличие ErisPulse>=2.7.1 с выводом предупреждения; при запуске выводится журнал версий
Соответствие стандартам (4.3.2)
Структура ответов и коды ошибок следуют спецификации ответов API.
Дополнение message_id в событиях сообщений
На верхнем уровне события сообщения добавлено стандартное поле message_id (берётся MsgId WeChat, при отсутствии — пустая строка в качестве запасного значения), модулю больше не нужно читать его из mp_msg_id.
Стандартный ответ
Все вызовы call_api / Send возвращают стандартный ответ: status / retcode / data / message_id / message + верхнеуровневый mp_raw. При успешной отправке пассивного ответа поле message — пустая строка (data.passive_reply=true означает, что отправка перехвачена как пассивный ответ).
Спецификация кодов ошибок
| retcode | Значение | Описание |
|---|---|---|
| 0 | Успех | — |
| 34100 | Сбой платформы | WeChat API вернул errcode != 0; исходный errcode сохраняется в mp_raw. Неудачное получение token также относится к этому коду |
| 10003 | Ошибка параметров / неверифицирован | Неверифицированный аккаунт (verified=false) вызывает сервисные сообщения вне контекста пассивного ответа |
Аккаунты и мультиаккаунтность
call_apiподдерживает два совместимых поля аккаунта:account_id(стандартное имя) /_account_id(старое имя); ApiDSL фреймворка (Api.Using(...)) адаптируется автоматическиSendчитаетsend_context(в качестве запасного варианта используется аккаунт события)get_self_infoдополняет стандартные поля:user_id(AppID официального аккаунта) /user_name/user_displayname(wechatmp:{имя аккаунта})
Реализованные возможности платформы
- Приём: callback-сообщения официального аккаунта и события подписки/отписки и др. (открытый/безопасный режим), проверка подписи
- Отправка: сервисные сообщения (Text/Image и др., через Send DSL)
- API: информация об аккаунте (appid) и состояние работы (минимальный набор)
Поддерживаемые типы отправки сообщений
| Метод | Описание | WeChat API |
|---|---|---|
Text(text) |
Отправка текста | Сервисное сообщение message/custom/send |
Image(file) |
Отправка изображения (автоматическая загрузка для получения media_id) | Сервисное сообщение + media/upload |
Voice(file) |
Отправка голосового сообщения (автоматическая загрузка для получения media_id) | Сервисное сообщение + media/upload |
Video(file, title, description) |
Отправка видео (автоматическая загрузка для получения media_id) | Сервисное сообщение + media/upload |
Music(url, title, description, ...) |
Отправка музыки | Сервисное сообщение |
News(articles) |
Отправка сообщения «изображение + текст» | Сервисное сообщение |
Template(template_id, data, url) |
Отправка шаблонного сообщения | message/template/send |
Menu(head_content, list, tail_content) |
Отправка сообщения меню | Сервисное сообщение msgmenu |
Raw_ob12(message) |
Отправка стандартных сегментов сообщений OneBot12 | - |
Описание медиафайлов
- Поддерживаются три типа параметров:
strURL (начинающийся сhttp:///https://): автоматически скачивается, затем загружаетсяstrпуть к локальному файлу: автоматически считывается, затем загружаетсяbytesдвоичные данные: загружаются напрямуюstrmedia_id: с префиксомmedia:можно напрямую повторно использовать уже загруженный media_id
- После загрузки получается временный медиаресурс
media_id, действительный 3 дня
Важные ограничения
- Сервисные сообщения можно отправлять проактивно только в течение 48 часов после взаимодействия пользователя с официальным аккаунтом
- По истечении 48 часов необходимо использовать шаблонные сообщения (сценарии, требующие авторизации пользователя)
- Неверифицированный сервисный аккаунт (
verified=false) не может отправлять сообщения проактивно, только пассивные ответы (см. выше раздел «Верифицированный сервисный аккаунт и пассивный ответ»)
Типы событий
События сообщений (message)
Все сообщения пользователей имеют detail_type: private (сценарий «один на один» официального аккаунта).
| MsgType WeChat | Тип сегмента сообщения | Описание |
|---|---|---|
text |
text |
Текстовое сообщение |
image |
image |
Сообщение с изображением |
voice |
voice |
Голосовое сообщение (с результатами распознавания речи) |
video |
video |
Видеосообщение |
shortvideo |
video |
Короткое видео (помечается mp_shortvideo) |
location |
location |
Сообщение с геолокацией |
link |
text |
Сообщение со ссылкой (преобразуется в текст) |
События уведомлений (notice)
Конкретный тип события различается по полю mp_event.
| Событие WeChat | mp_event |
Описание |
|---|---|---|
subscribe |
subscribe |
Подписка на официальный аккаунт |
unsubscribe |
unsubscribe |
Отписка |
SCAN |
scan |
Сканирование QR-кода с параметром |
LOCATION |
location_report |
Отправка данных о геолокации |
CLICK |
menu_click |
Нажатие пункта пользовательского меню |
VIEW |
menu_view |
Переход по ссылке меню |
TEMPLATESENDJOBFINISH |
template_send_finish |
Результат отправки шаблонного сообщения |
MASSSENDJOBFINISH |
mass_send_finish |
Результат массовой рассылки сообщений |
Расширенные поля платформы
Специфичные для WeChat поля в объекте события (префикс mp_):
| Поле | Тип | Описание |
|---|---|---|
mp_raw |
str | Исходные XML-данные |
mp_raw_type |
str | Исходный тип сообщения/события |
mp_msg_id |
str | ID сообщения WeChat |
mp_event |
str | Тип события (только для событий-уведомлений) |
mp_event_key |
str | Ключ события (нажатие меню/сканирование QR и т.п.) |
mp_to_user |
str | WeChat ID получателя (исходный ID официального аккаунта) |
mp_from_user |
str | OpenID отправителя |
mp_data |
dict | Разобранные XML-данные в виде словаря |
Расширенные методы событий
Регистрируются через register_event_mixin("mp", ...), вызываются напрямую на объекте события:
| Метод | Возвращаемое значение | Описание |
|---|---|---|
get_openid() |
str | OpenID отправителя |
get_msg_type() |
str | Исходный тип сообщения WeChat |
get_event() |
str | Тип события (только для событий-уведомлений) |
get_content() |
str | Чистый текстовый контент сообщения |
get_raw_xml() |
str | Исходные XML-данные |
Параметры конфигурации
Конфигурация нескольких аккаунтов
Каждый аккаунт соответствует одному официальному аккаунту:
[WechatMpAdapter.accounts.main]
appid = "wx1234567890abcdef"
appsecret = "your_app_secret_here"
token = "your_callback_token"
encoding_aes_key = "" # Требуется только для безопасного/совместимого режима (43 символа)
callback_path = "/mp/main" # Путь обратного вызова (callback)
verified = true # Является ли верифицированным сервисным аккаунтом (влияет на возможность проактивной отправки)
enable = true
[WechatMpAdapter.accounts.secondary]
appid = "wx0987654321fedcba"
appsecret = "another_app_secret"
token = "another_callback_token"
callback_path = "/mp/secondary"
enable = true
Описание полей конфигурации
| Поле | Обязательно | Описание |
|---|---|---|
appid |
Да | AppID официального аккаунта |
appsecret |
Да | AppSecret официального аккаунта (secret) |
token |
Нет | Токен проверки callback (рекомендуется указать для включения проверки подписи) |
encoding_aes_key |
Нет | Ключ шифрования/дешифрования сообщений (43 символа, обязателен в безопасном режиме) |
callback_path |
Нет | Шаблон пути обратного вызова, по умолчанию /mp/{account}, {account} заменяется именем аккаунта |
verified |
Нет | Является ли верифицированным сервисным аккаунтом, по умолчанию true (см. пояснение ниже) |
enable |
Нет | Включать ли аккаунт, по умолчанию true |
Верифицированный сервисный аккаунт и пассивный ответ (verified)
verified = true(по умолчанию, верифицированный сервисный аккаунт): можно в любой момент проактивно отправлять сервисные сообщения (в пределах 48-часового окна) и шаблонные сообщенияverified = false(неверифицированный аккаунт подписки):- Сервисные / шаблонные сообщения можно отправлять только в контексте пассивного ответа webhook (в течение 15 секунд после получения сообщения от пользователя, один ответ) — адаптер автоматически перехватывает отправку как пассивный ответ
- Проактивная отправка (например, из запланированных задач) возвращает ошибку
retcode=10003(неверифицирован)
Описание режимов шифрования
Официальный аккаунт WeChat предоставляет три режима шифрования/дешифрования сообщений:
| Режим | Описание | encoding_aes_key | Поле проверки |
|---|---|---|---|
| Открытый режим | Передача XML в открытом виде | Не требуется | signature |
| Совместимый режим | Одновременно присутствуют открытый текст и шифртекст | Опционально | signature / msg_signature |
| Безопасный режим | Всё зашифровано | Обязателен | msg_signature |
Данный адаптер автоматически обрабатывает:
- Открытый режим: проверка
signature, прямой разбор XML - Безопасный/совместимый режим: обнаружение поля
Encrypt, проверкаmsg_signature, дешифрование с использованием AES-256-CBC - Дешифрование зависит от библиотеки
cryptography(объявлена в dependencies)
Маршруты обратного вызова
Адаптер регистрирует два маршрута (GET + POST) для каждого включённого аккаунта:
- GET: проверка подключения сервера WeChat; после проверки подписи возвращается
echostr - POST: приём сообщений и событий от пользователей; проверка подписи → дешифрование (при необходимости) → преобразование → emit
К фактическим путям доступа автоматически добавляется префикс модуля; например, при зарегистрированном пути /mp/main
фактические пути доступа: /mp_{account}_verify/mp/main и /mp_{account}_message/mp/main.
Ответы API
Все вызовы call_api возвращают стандартизированный ответ:
- Успех:
status: "ok",retcode: 0 - Сбой:
status: "failed",retcode: 34100(сбой платформы; исходный errcode сохраняется вmp_raw) или10003(ошибка параметров / неверифицирован) - Всегда содержит
mp_raw(исходный ответ) и верхнеуровневыйmessage_id(при отсутствии — пустая строка)