Skip to content
EdgeCrab EdgeCrab EdgeCrab

WeChat (Weixin) Setup

The Weixin adapter connects EdgeCrab to WeChat (微信) through the iLink Bot API, which provides a POST-based long-polling interface with persistent sync buffer for reliable message ordering across restarts.

Prerequisites

Section titled “Prerequisites”
  1. An iLink Bot account with API access
  2. A configured bot token from the iLink Bot dashboard
  3. Your WeChat account ID

Environment Variables

Section titled “Environment Variables”
VariableRequiredDescription
WEIXIN_TOKENYesiLink Bot API token
WEIXIN_ACCOUNT_IDYesYour WeChat account identifier
WEIXIN_BASE_URLNoCustom API base URL (default: iLink Bot API)
WEIXIN_CDN_BASE_URLNoCDN endpoint for media upload/download
WEIXIN_ALLOWED_USERSNoComma-separated list of allowed user IDs
WEIXIN_DM_POLICYNoDM access policy: open or allowlist
WEIXIN_GROUP_POLICYNoGroup access policy: open or allowlist

Gateway Configuration

Section titled “Gateway Configuration”
~/.edgecrab/config.yaml
gateway:
  platforms:
    weixin:
      enabled: true
Terminal window
# Start with WeChat
WEIXIN_TOKEN=your-bot-token \
WEIXIN_ACCOUNT_ID=your-account-id \
edgecrab gateway start

How It Works

Section titled “How It Works”
WeChat User → WeChat Server → iLink Bot API → POST long-poll → EdgeCrab Gateway → Agent
                                                                        ↓
WeChat User ← WeChat Server ← iLink Bot API ←──────────── EdgeCrab Reply
  1. EdgeCrab POST-polls the iLink Bot API with a sync buffer for reliable message ordering
  2. When messages arrive, media items (images, voice, video, files) are downloaded from CDN and decrypted via AES-128-ECB
  3. Messages are dispatched to the agent loop with text and attachment metadata
  4. The agent processes the message and generates a reply
  5. Outbound media is AES-128-ECB encrypted and uploaded to CDN before sending
  6. If the session expires (errcode -14), the adapter auto-recovers without losing state

Security

Section titled “Security”
  • AES-128-ECB media encryption: Media files are encrypted/decrypted for CDN transport
  • AES-256-CBC XML encryption: WeCom XML payloads use AES-256-CBC encryption
  • User allowlist: Set WEIXIN_ALLOWED_USERS to restrict which WeChat users can interact with the bot
  • Token authentication: All API calls are authenticated with the bot token
  • Session-expired recovery: Detects errcode -14 and re-authenticates automatically

Features

Section titled “Features”
  • Text messaging (send and receive)
  • Image, voice, video, and file attachments (send and receive)
  • AES-128-ECB encrypted CDN media pipeline (upload + download)
  • POST-based polling with persistent sync buffer
  • User allowlist filtering (DM and group policies)
  • Automatic message deduplication
  • Session-expired auto-recovery
  • Context token echo for conversation threading
  • Markdown reformatting for WeChat’s text-only display
  • Typing indicator support via ticket-based API

Troubleshooting

Section titled “Troubleshooting”
IssueFix
No messages receivedVerify WEIXIN_TOKEN and WEIXIN_ACCOUNT_ID are correct
Unauthorized usersAdd user IDs to WEIXIN_ALLOWED_USERS
Connection timeoutsCheck network connectivity to iLink Bot API
Media download failsVerify WEIXIN_CDN_BASE_URL is reachable
Session expired errorsNormal — adapter auto-recovers via re-authentication