Skip to content

feat(gateway): add WeChat Official Account platform adapter - #2481

Closed
teknium1 wants to merge 1 commit into
mainfrom
hermes/hermes-baa39faf
Closed

feat(gateway): add WeChat Official Account platform adapter#2481
teknium1 wants to merge 1 commit into
mainfrom
hermes/hermes-baa39faf

Conversation

@teknium1

Copy link
Copy Markdown
Contributor

Summary

Adds WeChat support using the official WeChat Official Account API — no third-party bridges or competitor dependencies.

Replaces PR #2425 which depended on OpenClaw's WeixinClawBot service.

How it works

The adapter runs an aiohttp webhook server. WeChat pushes messages to it via HTTP POST with XML payloads. Replies go back via the Customer Service Message API (JSON).

  • Receive: WeChat pushes XML → adapter parses → standard MessageEvent
  • Send: Agent response → JSON POST to api.weixin.qq.com/cgi-bin/message/custom/send
  • Auth: AppID + AppSecret → access_token (auto-refreshed, 2h TTL)
  • Verification: SHA1 signature handshake per WeChat spec

Configuration

WECHAT_TOKEN=your-verification-token
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=your-app-secret
# Optional
WECHAT_PORT=8680
WECHAT_HOME_CHANNEL=openid_abc123

Integration points

File Change
gateway/platforms/wechat.py New adapter (351 lines)
gateway/config.py Platform.WECHAT enum + env overrides
gateway/run.py Adapter factory
cron/scheduler.py deliver=wechat support
agent/prompt_builder.py Plain-text platform hint

Note

WeChat Official Accounts require verification through WeChat's admin dashboard. Users need a Service Account (not Subscription Account) for the Customer Service Message API. This is China-market focused — international users may find WeChat Work/WeCom more accessible.

Test plan

  • Adapter imports and initializes correctly
  • No regressions in gateway/cron tests

Adds WeChat support using the official WeChat Official Account API
(not third-party bridges). The adapter:

- Runs an aiohttp webhook server to receive message pushes from WeChat
- Handles WeChat's server verification handshake (SHA1 signature)
- Parses XML message payloads into standard MessageEvents
- Sends replies via the Customer Service Message API (JSON)
- Manages access_token lifecycle (auto-refresh, 2h TTL)
- Message deduplication with configurable window
- Auto-splits long messages at the 2048 char limit

Integration points:
- gateway/config.py: Platform.WECHAT enum, env overrides, home channel
- gateway/run.py: adapter factory
- cron/scheduler.py: deliver=wechat support
- agent/prompt_builder.py: plain-text platform hint

Configuration:
  WECHAT_TOKEN (verification token)
  WECHAT_APP_ID (Official Account AppID)
  WECHAT_APP_SECRET (Official Account AppSecret)
  WECHAT_PORT (default: 8680)
  WECHAT_HOME_CHANNEL / WECHAT_HOME_CHANNEL_NAME
@teknium1
teknium1 force-pushed the hermes/hermes-baa39faf branch from 84e7a33 to 0dd5d58 Compare March 22, 2026 13:06
@teknium1

Copy link
Copy Markdown
Contributor Author

Holding off on merge — the adapter code works but WeChat Official Account API requires Chinese business registration, ICP filing, and verification that 99% of users can't get. No competitor has shipped WeChat support for the same reason.

The code is saved as a reference implementation. When a user with actual WeChat access wants to test, or when we add Enterprise WeChat (WeCom) support (more accessible, where the Tencent+AI momentum actually is), we'll revisit.

@teknium1 teknium1 closed this Mar 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant