v1.0.0 to v1.0.1

---

name: wechat-binding

author: starchild

tags: [wechat, binding, connection, qrcode, ilink]

---

# 📱 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.