ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Адаптер официального аккаунта 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 -

Описание медиафайлов

  • Поддерживаются три типа параметров:
    • str URL (начинающийся с http:// / https://): автоматически скачивается, затем загружается
    • str путь к локальному файлу: автоматически считывается, затем загружается
    • bytes двоичные данные: загружаются напрямую
    • str media_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 (при отсутствии — пустая строка)