# Wechat Binding

> WeChat binding: QR scan, bind, unbind, reconnect, status check. Use when setting up or repairing WeChat delivery (e.g. connect WeChat, scan QR, why isn't WeChat pushing, disconnect WeChat).

- Skill: `om-scogo/wechat-binding` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add om-scogo/wechat-binding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/om-scogo/wechat-binding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: om-scogo (https://skillmd.com/u/om-scogo)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/om-scogo/wechat-binding

---


# 📱 WeChat Binding

Connect / reconnect / disconnect the user's WeChat account so the agent can push messages via `send_to_wechat`.

The `wechat` tool stays built-in. This SKILL.md is the reference doc.

## See also
- `config/context/references/messaging-channels.md` — how to actually send messages once bound
- `skills/tg-bot-binding/SKILL.md` — analogous Telegram flow

---

## Typical binding flow

```
qrcode → user scans → qrcode_status(qrcode=...) → connect(bot_token=...)
```

1. **Generate QR:** `wechat(action="qrcode")` — saves an image to workspace, returns `qrcode` (id) + `file_path`.
2. **Show the QR to the user.** On web channel: include the `file_path` so the frontend renders the image. On TG/WeChat channel: send the image via `send_to_telegram` with the `file_path`.
3. **Wait for the user to scan + confirm in WeChat.** Don't auto-poll — let them say "scanned" / "done" first.
4. **Poll for completion:** `wechat(action="qrcode_status", qrcode=<id from step 1>)`. Returns `bot_token` once scan + confirm completes.
5. **Connect:** `wechat(action="connect", bot_token=<from step 4>)`. Optional: `ilink_bot_id`, `ilink_user_id` if the user has multiple WeChat accounts.
6. **Confirm to user:** "WeChat connected. You can now push messages with send_to_wechat."

---

## Actions

| action | required | purpose |
|---|---|---|
| `status` | — | Current WeChat connection state. Use before reconnect, to verify binding. |
| `qrcode` | — | Generate QR code image (saved to workspace). Returns `qrcode` id + `file_path`. |
| `qrcode_status` | `qrcode` | Poll whether user has scanned + confirmed. Returns `bot_token` on success. |
| `connect` | `bot_token` | Complete a NEW WeChat connection (after first-ever QR scan). Optional: `ilink_bot_id`, `ilink_user_id`. |
| `disconnect` | — | Terminate current WeChat session (unlink). |
| `reconnect` | `bot_token` | Re-establish a previously-bound WeChat (token from a fresh QR scan). |

---

## connect vs. reconnect

- **`connect`** — first-time binding. The user has NEVER bound this WeChat before.
- **`reconnect`** — the user was previously connected, the connection dropped (e.g. ilink session expired), and they just scanned a fresh QR.

When in doubt, call `status` first:
- `connected: false` + no prior history → `connect`
- `connected: false` + prior history exists → `reconnect`

---

## Channel-aware QR display

| User channel | How to show the QR |
|---|---|
| **Web** | Include `file_path` in your reply — frontend renders it inline |
| **Telegram** | `send_to_telegram(file_path=<qr_path>, message_type="photo")` |
| **WeChat** | (You can't — they're trying to bind WeChat in the first place. Tell them to open the web app.) |

---

## Critical rules

- **Don't auto-poll** `qrcode_status` after `qrcode`. Wait for user confirmation that they scanned + confirmed in WeChat. Auto-polling spams the upstream API.
- **Each `qrcode` call generates a fresh image.** Don't re-use an old `qrcode` id with a new image — the upstream session is tied to the id.
- **Never paste `bot_token` in chat.** It's a credential. Once you have it from `qrcode_status`, immediately pass it to `connect` / `reconnect` and don't echo it back to the user.
- **`disconnect` is destructive** — confirm with the user before calling it.