ContextQMD
Back to Eliza

WeChat Connector

packages/docs/connectors/wechat.md

2.0.14.7 KB
Original Source

WeChat Connector

Connect your agent to WeChat for personal and group messaging via a third-party proxy service using the @elizaos/plugin-wechat package.

Status: The @elizaos/plugin-wechat package is not currently available in the plugin registry. This page documents the planned connector interface. Check the plugin registry for availability updates.

<Warning> This connector is **not included** in the bundled plugin registry (`plugins.json`). It is a Eliza-specific plugin that must be installed separately. Run `bun run setup:upstreams` to make it available from the local checkout. </Warning> <Warning> The `@elizaos/plugin-wechat` package is not included in the bundled plugin registry (`plugins.json`). It may be available as an upstream elizaOS plugin. Install it manually from npm if available. </Warning>

Availability: @elizaos/plugin-wechat is a Eliza-local plugin that is not included in the bundled plugins.json registry. It ships as a CI stub and requires the full plugin package to be available locally or via npm.

Overview

The WeChat connector is a plugin that bridges your agent to WeChat via a user-supplied proxy service. Unlike most connectors which use official platform APIs, the WeChat connector relies on a third-party proxy that bridges WeChat's protocol. Your agent authenticates by scanning a QR code displayed in the terminal on first startup.

  • A WeChat account
  • A proxy service URL and API key for bridging WeChat's protocol

Privacy notice: The WeChat connector sends your API key and message payloads through the configured proxy service. Only point proxyUrl at infrastructure you operate yourself or explicitly trust for that message flow.

Configuration

NameRequiredDescription
WECHAT_API_KEYYesProxy service API key

Additional configuration is done via the connectors.wechat config in ~/.eliza/eliza.json:

Config FieldTypeDefaultDescription
apiKeystring--Proxy service API key (required)
proxyUrlstring--Proxy service URL (required)
webhookPortnumber18790Webhook listener port
deviceType"ipad" / "mac""ipad"Device emulation type
enabledboolean--Explicitly enable/disable
features.imagesbooleanfalseEnable image send/receive
features.groupsbooleanfalseEnable group chat support

The connector auto-enables when apiKey is truthy at the top level, or an accounts entry has a truthy apiKey.

Configure in ~/.eliza/eliza.json:

json
{
  "connectors": {
    "wechat": {
      "apiKey": "YOUR_API_KEY",
      "proxyUrl": "https://your-proxy-service.example.com"
    }
  }
}

Disabling

To explicitly disable the connector even when an API key is present:

json
{
  "connectors": {
    "wechat": {
      "apiKey": "YOUR_API_KEY",
      "proxyUrl": "https://your-proxy-service.example.com",
      "enabled": false
    }
  }
}

Setup

  1. Obtain an API key and proxy service URL.
  2. Add the credentials to connectors.wechat in your config.
  3. Start Eliza -- on first start, the plugin displays a QR code in the terminal.
  4. Scan the QR code with WeChat on your phone to link the session.
  5. Sessions persist automatically -- subsequent starts reuse the existing session unless it has expired.

Multi-Account Support

Run multiple WeChat accounts using the accounts map:

json
{
  "connectors": {
    "wechat": {
      "accounts": {
        "personal": {
          "apiKey": "KEY_1",
          "proxyUrl": "https://proxy.example.com",
          "deviceType": "ipad"
        },
        "work": {
          "apiKey": "KEY_2",
          "proxyUrl": "https://proxy.example.com",
          "deviceType": "mac",
          "enabled": false
        }
      },
      "features": {
        "groups": true
      }
    }
  }
}

Each account has its own API key, proxy URL, and session. Per-account fields override top-level settings.

Features

  • Text messaging — DM conversations enabled by default
  • Group chats — Participate in group conversations (enable with features.groups: true)
  • Image support — Send and receive images (enable with features.images: true)
  • QR code login — Authenticate by scanning a QR code, with automatic session persistence
  • Multi-account — Run multiple WeChat accounts from a single agent via the accounts map
  • Device emulation — Choose between iPad or Mac client emulation