5.6 KiB
OfficialAccount EBA Adapter
Adapter directory: src/langbot/pkg/platform/adapters/officialaccount/
Manifest name: officialaccount-eba
Status: partial migration. Unit/API-shape coverage is present, and private text plugin-e2e-ui plus safe API evidence has been verified against the dev.rockchin.top Official Account fixture. Proactive outbound send_message remains not supported by this adapter because WeChat Official Account replies must be tied to inbound webhook windows.
Config
| Field | Required | Notes |
|---|---|---|
webhook_url |
no | Generated by LangBot and copied into the Official Account callback settings. |
token |
yes | WeChat callback token. |
EncodingAESKey |
yes | WeChat message encryption key. |
AppID |
yes | Official Account app ID. |
AppSecret |
yes | Official Account app secret. |
Mode |
yes | drop waits for an in-callback reply; passive returns the loading text first and queues the answer for the user's next message. |
LoadingMessage |
no | Only used by passive mode. |
api_base_url |
no | Optional API base URL for proxy deployments. |
Events
| Event | Evidence | Notes |
|---|---|---|
message.received |
plugin-e2e-ui, unit | Text UI message verified through WeChat Official Account on dev.rockchin.top; image and voice webhook payloads are covered by unit tests. |
platform.specific |
unit | Subscribe/menu/etc. native events are emitted as structured PlatformSpecificEvent. |
Common APIs
| API | Evidence | Notes |
|---|---|---|
reply_message |
unit | Queues/passively returns text through the inbound webhook source event. |
get_message |
plugin-e2e-ui, unit | Cached inbound message retrieved by EBAEventProbe platform API sweep. |
get_user_info |
plugin-e2e-ui, unit | Cached inbound sender retrieved by EBAEventProbe platform API sweep. |
get_friend_list |
plugin-e2e-ui, unit | Cached inbound sender list retrieved by EBAEventProbe platform API sweep. |
call_platform_api |
plugin-e2e-ui, unit | Safe diagnostic actions verified through get_mode and get_cached_response_status. |
send_message |
not-supported | Official Account customer-service proactive messaging is not implemented by the existing SDK adapter; only webhook reply is supported here. |
Platform APIs
| Action | Evidence | Notes |
|---|---|---|
get_mode |
plugin-e2e-ui, unit | Returned {"mode": "drop", "longer_response": false} in live probe. |
get_cached_response_status |
plugin-e2e-ui, unit | Returned {"pending": false} in live probe. |
Components
| Receive Component | Evidence | Notes |
|---|---|---|
Source |
plugin-e2e-ui, unit | Uses MsgId and CreateTime; live UI text message included Source. |
Plain |
plugin-e2e-ui, unit | Live UI text message mapped to Plain. |
Image |
unit | PicUrl and MediaId map to common Image. |
Voice |
unit | MediaId maps to common Voice. |
Unknown |
unit | Unsupported message/event types do not crash. |
At, AtAll, File, Quote, Face, Forward, mixed chain |
not-supported | WeChat Official Account inbound webhook payloads used by the current SDK do not expose these as common structured components. |
| Send Component | Evidence | Notes |
|---|---|---|
Plain |
unit | Sent as webhook reply text. |
Image, Voice, File, Quote, At, AtAll, Face, Forward, mixed chain |
not-supported | Existing SDK reply path is text XML only; non-text components degrade to readable placeholders in tests and are not declared as supported outbound components. |
Verification Record
Test date: 2026-05-28
Endpoint/simulator: dev.rockchin.top with WeChat desktop client and a real subscribed Official Account conversation. The running EBA test stack used SDK standalone runtime ports 5400/5401, LangBot from /home/wgc/LangBotxg/LangBotEbaTest, and EBAEventProbe.
Verified UI message: EBA officialaccount single probe 2026-05-28 16:53
Observed event/API evidence:
MessageReceived:bot_uuid=d7c46880-a9f8-431a-9172-5d3e0d663dbc,adapter_name=officialaccount-eba,chat_type=private,chat_id=ovH9L7OW6hNpWZWvp_NMmypVh26w,message_chain=[Source, Plain].- Common safe APIs through probe platform sweep:
get_message,get_user_info,get_friend_list. - Platform APIs through
call_platform_api:get_mode,get_cached_response_status. send_messageand outbound component sweep returned explicitNotSupportedError: send_message:official_account_requires_inbound_webhook_reply, as expected for this adapter.
Standalone runtime command:
cd langbot-plugin-sdk
uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
Probe plugin: data/plugins/LangBot__EBAEventProbe when live credentials are available.
Adapter live probe:
uv run python -m py_compile tests/e2e/live_officialaccount_eba_probe.py
OFFICIALACCOUNT_TOKEN=... OFFICIALACCOUNT_ENCODING_AES_KEY=... OFFICIALACCOUNT_APP_SECRET=... OFFICIALACCOUNT_APP_ID=... uv run python tests/e2e/live_officialaccount_eba_probe.py
Evidence JSONL path: /home/wgc/LangBotxg/LangBotEbaTest/data/temp/officialaccount_eba_plugin_probe.jsonl for plugin E2E, or data/temp/officialaccount_eba_probe.jsonl for direct adapter live probe.
Destructive operations: none.
Blocked items:
plugin-e2e-outbound: proactivesend_messageis not supported for this adapter; Official Account responses must be produced through the inbound webhook reply window.- Inbound image and voice live UI evidence remains pending; webhook conversion is covered by unit tests.