Адаптер WeChatMp - Документация по функциональности платформы

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

• Название модуля: ErisPulse-WechatMpAdapter
• Идентификатор платформы: mp (альтернативное имя: wechat_mp)
• Версия модуля: 4.1.0
• Разработчик: ErisPulse
• Зависимости: cryptography

Обновление парадигмы v5 (4.2.0)

• Наследование BaseConverter: Общие поля конвертера строятся фреймворком build_base_event
• Минимальный набор DSL-команд API: get_self_info (appid) / get_status / get_version / get_supported_actions
• Мягкая зависимость фреймворка: Во время выполнения проверяется наличие ErisPulse>=2.7.1 и выводится предупреждение; при запуске выводится лог версии

Поддерживаемые возможности платформ

• Прием: Обратные сообщения от публичного аккаунта и события подписки/отписки и т.д. (в открытом виде/в защищенном режиме), проверка подлинности подписи
• Отправка: Сообщения службы поддержки (Text/Image и т.д., через Send DSL)
• API: Информация о счете (appid) и состояние выполнения (минимальный набор)

Поддерживаемые типы отправки сообщений

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

• Поддерживаются три типа параметров:
  • str URL (начинается с http:// или https://): автоматически загружается и загружается на сервер
  • str локальный путь к файлу: автоматически читается и загружается на сервер
  • bytes двоичные данные: загружаются напрямую
  • str media_id: с префиксом media: можно повторно использовать уже загруженный media_id
• После загрузки получается временный материал media_id, срок действия которого составляет 3 дня

Важные ограничения

• Сообщения клиентской поддержки можно отправлять только в течение 48 часов после взаимодействия пользователя с публикацией
• После истечения 48 часов необходимо использовать шаблонные сообщения (требуется сценарий авторизации пользователя)
• Непроверенные сервисные аккаунты (с verified=false) не могут отправлять сообщения активно, могут только отвечать пассивно (см. выше «Проверенные сервисные аккаунты и пассивные ответы»)

Типы событий

События сообщений (message)

Все сообщения от пользователей имеют detail_type: private (сценарий 1v1 для публичных аккаунтов).

События уведомлений (notice)

Типы событий различаются по полю mp_event.

Расширение платформы

Поле, специфичное для WeChat, в объекте события (префикс mp_):

Методы расширения событий

Регистрируются с помощью register_event_mixin("mp", ...), после чего можно напрямую вызывать на объекте события:

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

Конфигурация нескольких аккаунтов

Каждый аккаунт соответствует одному публичному аккаунту:

[WechatMpAdapter.accounts.main]
appid = "wx1234567890abcdef"
appsecret = "your_app_secret_here"
token = "your_callback_token"
encoding_aes_key = ""                    # Требуется только для режима безопасности/совместимости (43 символа)
callback_path = "/mp/main"               # Путь обратного вызова
verified = true                          # Является ли аккаунтом с подтвержденной сертификацией (влияет на возможность отправки сообщений)
enable = true

[WechatMpAdapter.accounts.secondary]
appid = "wx0987654321fedcba"
appsecret = "another_app_secret"
token = "another_callback_token"
callback_path = "/mp/secondary"
enable = true

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

Подтвержденный сервисный аккаунт и пассивные ответы (verified)

• verified = true (по умолчанию, подтвержденный сервисный аккаунт): можно использовать сообщения службы поддержки для отправки активных сообщений (в течение 48 часов) и шаблонные сообщения.
• verified = false (не подтвержденный аккаунт подписки):
  • Сообщения службы поддержки / шаблонные сообщения можно отправлять только в контексте пассивного ответа webhook (в течение 15 секунд после получения сообщения от пользователя, один раз) — адаптер автоматически перехватывает отправку и преобразует её в пассивный ответ.
  • Активная отправка (например, по расписанию) вернет ошибку с кодом retcode=34003.

Описание режимов шифрования

Мини-приложение WeChat предоставляет три режима шифрования и расшифровки сообщений:

Адаптер автоматически обрабатывает:

• Режим в открытом виде: проверяет signature и напрямую анализирует XML
• Безопасный/совместимый режим: обнаруживает поле Encrypt, проверяет msg_signature и расшифровывает с помощью AES-256-CBC
• Расшифровка зависит от библиотеки cryptography (уже указана в зависимостях)

Callback-маршруты

Адаптер регистрирует два маршрута (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: 34000+errcode
• Всегда включает mp_raw (сырой ответ) и message_id