elizaos--eliza/plugins/plugin-wechat/README.md

@elizaos/plugin-wechat

WeChat connector plugin for elizaOS via proxy API.

Adds WeChat DM and group messaging to an Eliza agent. The plugin connects to a third-party WeChat proxy service, starts a local webhook server to receive inbound messages, and registers a MessageConnector so the agent can send/ receive text and images, resolve contacts, and read chat history.

Features

• Text and image messaging (DM and group)
• Multi-account support
• QR-code login flow (prints URL to terminal; scan with WeChat mobile)
• Webhook-based inbound message delivery with deduplication
• Automatic session health checks and re-login on expiry

Install

npx elizaos plugins add @elizaos/plugin-wechat

Configuration

Environment variables (single-account)

Env Var	Required	Description
WECHAT_API_KEY	Yes	Proxy service API key
WECHAT_PROXY_URL	Yes	Base URL of the WeChat proxy (https:// only)
ELIZA_WECHAT_WEBHOOK_PORT	No	Webhook listener port (default: 18790)

Character config block (recommended)

{
  "connectors": {
    "wechat": {
      "apiKey": "YOUR_API_KEY",
      "proxyUrl": "https://your-proxy.example.com",
      "webhookPort": 18790,
      "deviceType": "ipad",
      "loginTimeoutMs": 300000,
      "features": {
        "images": true,
        "groups": true
      }
    }
  }
}

Multi-account

{
  "connectors": {
    "wechat": {
      "accounts": {
        "main":    { "apiKey": "...", "proxyUrl": "https://proxy1.example.com" },
        "support": { "apiKey": "...", "proxyUrl": "https://proxy2.example.com" }
      }
    }
  }
}

How it works

1. On agent startup the plugin reads config, spins up a local HTTP webhook server (default port 18790), and connects to the proxy.
2. If the WeChat session is not active, it fetches a QR-code login URL and prints it to the terminal. Scan it with the WeChat mobile app.
3. Once logged in, the proxy pushes inbound messages to the webhook server. The plugin normalises the payload and routes it through the elizaOS message pipeline (the agent reads and replies normally).
4. Outgoing replies are chunked at 2 000 characters and sent back via the proxy.
5. A background health check runs every 60 seconds and re-initiates login if the session expires.