Zhin.js

English

简体中文

English

简体中文

Appearance

Documentation Sync

This page is auto-generated from plugins/adapters/wechat-mp/README.md. Please edit the in-package README and then run pnpm sync:adapter-docs.

@zhin.js/adapter-wechat-mp ​

Zhin.js WeChat Official Account adapter (Plugin Runtime). Sends and receives messages via the Runtime Host HTTP Webhook.

Features ​

  • Webhook event reception (httpHostToken GET signature verification + POST messages)
  • Signature verification with optional AES encryption/decryption
  • Automatic Access Token refresh
  • XML message parsing
  • Convention-based defineAdapter / definePlugin (no usePlugin needed)

Installation ​

bash
pnpm add @zhin.js/adapter-wechat-mp

Plugin Runtime ​

  • @zhin.js/adapter — convention-based adapters/wechat-mp/index.ts (defineAdapter)
  • @zhin.js/core — Endpoint.emit(...) inbound, outboundMessageToken outbound
  • @zhin.js/host-http — httpHostToken registers Webhook route (not legacy host-router/Koa)
  • zhin.js — plugin.ts (definePlugin)
  • Configuration goes to plugins.<instanceKey> via the plugin's schema.json

Inbound: gateway.receive({ conversation, message, content, sender, metadata }) (always kind: 'private', conversation.id is the openid) Outbound: send({ conversation, payload }) -> passive reply XML (default) or Customer Service Message API (replyMode: customer_service; touser is conversation.id)

Prerequisites ​

RequirementDescription
Official AccountA registered WeChat Official Account; obtain AppID and AppSecret from the WeChat Official Account Platform
Server configurationConfigure Token (must match the token field); server URL must be publicly accessible
host-httpRequired — Runtime Host provides HTTP; the adapter registers GET/POST on path
Response time limitWeChat requires a response within 5 seconds; timeouts will cause connection failure
Reply modeDefault replyMode: passive (subscription account passive reply); service accounts can set customer_service
Message encryptionOptional; encrypt: true + encodingAESKey; encryptMode: compatible (default) or secure

Required fields (endpoints[i]): id, appId, appSecret, token. AdapterIndex merges instance defaults into every endpoint; the protocol receives only one expanded endpoint config.

Minimal Configuration ​

yaml
# zhin.config.yml (Plugin Runtime)
plugins:
  wechat-mp:
    path: /wechat/webhook
    endpoints:
      - id: my-wechat-bot
        appId: "${WECHAT_APP_ID}"
        appSecret: "${WECHAT_APP_SECRET}"
        token: "${WECHAT_TOKEN}"

The root plugin zhin.plugins (or project graph) must reference @zhin.js/adapter-wechat-mp (instanceKey: wechat-mp). The Runtime Host (http) must already be listening for the Webhook to be reachable.

Optional Fields ​

  • path: Webhook path, default /wechat/webhook
  • replyMode: passive (default) | customer_service
  • passiveReplyTimeoutMs: Passive reply wait limit, default 4500
  • encrypt / encodingAESKey / encryptMode

WeChat Official Account Configuration ​

  1. Log in to the WeChat Official Account Platform
  2. Obtain AppID and AppSecret from "Development -> Basic Configuration"
  3. Configure the server address (URL): https://your-server/wechat/webhook (no /api prefix; map through reverse proxy as needed)
  4. Set the Token (must match the token in the configuration file)
  5. If message encryption is needed, set the EncodingAESKey

Troubleshooting ​

SymptomInvestigation
Server configuration verification failuretoken must match the Official Account Platform; URL should be https://<host>/wechat/webhook; Runtime Host must be listening and publicly accessible
Not receiving user messagesCheck if the Official Account type supports the message interface; check if the user has followed the account; path must match the Official Account Platform URL; endpoint must have called open()
Reply timeout / no replyDefault passive reply must complete within ~4.5s; consider switching to replyMode: customer_service (requires Customer Service API permissions)
48001 api unauthorizedUnverified subscription accounts do not have Customer Service API access; keep the default replyMode: passive
Encryption mode errorencodingAESKey, encrypt must match the Official Account Platform's "Security Mode" settings

AI Tools ​

See skills/wechat-mp/SKILL.md for skill documentation.

License ​

MIT License