Skill: WeChat Messaging via weixin-agent-cli

Use the weixin-agent-cli command-line tool to send and receive WeChat (微信) messages. All commands output JSON to stdout.

Prerequisites

• The weixin-agent-cli tool must be installed and available in PATH
• An account must be logged in (run weixin-agent-cli login in an interactive terminal first)

Key Concepts

• Account ID: Each logged-in WeChat bot has an account ID (e.g. [email protected]). If only one account exists, it's used automatically.
• User ID: WeChat users are identified by IDs ending in @im.wechat (e.g. [email protected]).
• Context Token: Required for sending messages. Automatically cached when you receive a message from a user via poll. You must poll at least once before you can send to a user.

Workflow

1. Check Accounts

weixin-agent-cli accounts

Returns a JSON array of registered accounts with their status.

2. Poll for Messages

weixin-agent-cli poll
# With timeout (ms):
weixin-agent-cli poll --timeout 15000
# Specific account:
weixin-agent-cli poll --account "[email protected]"

Output format:

{
  "accountId": "[email protected]",
  "total": 3,
  "messages": [
    {
      "from": "[email protected]",
      "to": "[email protected]",
      "message_id": 12345,
      "message_type": "user",
      "message_state": "finish",
      "timestamp": 1711700000000,
      "text": "Hello, bot!"
    }
  ]
}

The messages array only contains completed user messages (bot echoes and generating states are filtered out).

Watch Mode (continuous polling)

weixin-agent-cli poll --watch
weixin-agent-cli poll --watch --timeout 10000

Outputs NDJSON (one JSON object per line). Empty polls (no user messages) are skipped. Runs until interrupted with Ctrl+C.

{"accountId":"[email protected]","total":1,"messages":[{"from":"[email protected]","text":"Hi"}]}
{"accountId":"[email protected]","total":1,"messages":[{"from":"[email protected]","text":"Second msg"}]}

3. Send a Text Message

weixin-agent-cli send --to "[email protected]" --text "Hello from the bot!"

Important: You must have received at least one message from the target user (via poll) before sending, so the context token is available.

4. Send a Media File

# Image
weixin-agent-cli send-media --to "[email protected]" --file "/path/to/image.png"

# Video with caption
weixin-agent-cli send-media --to "[email protected]" --file "/path/to/video.mp4" --text "Check this out"

# Document
weixin-agent-cli send-media --to "[email protected]" --file "/path/to/report.pdf"

File type is detected from the extension. Supported categories:

• Images: png, jpg, jpeg, gif, webp, bmp
• Video: mp4, mov, webm, mkv, avi
• Files: pdf, doc/docx, xls/xlsx, ppt/pptx, txt, csv, zip, tar, gz

5. Send Typing Indicator

# Start typing
weixin-agent-cli typing --to "[email protected]"

# Cancel typing
weixin-agent-cli typing --to "[email protected]" --cancel

Error Handling

All errors are written to stderr and the process exits with code 1. Check the JSON output success field or the exit code to detect failures.

Typical Agent Loop

Single-poll approach:

# Poll for new messages
RESULT=$(weixin-agent-cli poll --timeout 15000)

# Parse messages from JSON output, process each one
# Then reply:
weixin-agent-cli send --to "$FROM_USER" --text "$REPLY_TEXT"

Watch mode approach (continuous):

# Stream messages continuously, process each NDJSON line as it arrives:
weixin-agent-cli poll --watch | while IFS= read -r line; do
  echo "$line" | process_message_and_reply
done

Multi-Account

With multiple accounts, always pass --account <id> (or -a <id>):

weixin-agent-cli poll --account "[email protected]"
weixin-agent-cli send --to "[email protected]" --text "Hi" --account "[email protected]"