wechat-binding

starchild-ai-agent/official-skills

Connect, scan, and manage WeChat account binding for message delivery.

What is wechat-binding?

Enables QR-code-based WeChat account binding so agents can push messages via send_to_wechat. Use this skill to set up new WeChat connections, reconnect after session loss, check binding status, or disconnect accounts.

Generate QR codes for WeChat account scanning and binding
Poll for scan completion and retrieve bot tokens securely
Connect new WeChat accounts or reconnect previously-bound ones
Check current WeChat connection status
Disconnect and unlink WeChat accounts

How to install wechat-binding

npx skills add https://github.com/starchild-ai-agent/official-skills --skill wechat-binding

Claude Code

Cursor

Windsurf

Cline

How to use wechat-binding

1.Call wechat(action="qrcode") to generate a QR code image and receive a qrcode id and file_path
2.Display the QR image to the user (via web inline, Telegram photo, or other channel)
3.Wait for the user to confirm they have scanned and confirmed in WeChat—do not auto-poll
4.Call wechat(action="qrcode_status", qrcode=<id>) to check if scan completed and retrieve the bot_token
5.Call wechat(action="connect", bot_token=<token>) for first-time binding or wechat(action="reconnect", bot_token=<token>) if reconnecting a previously-bound account
6.Confirm to the user that WeChat is now connected and ready for message delivery

Use cases

Good for

User wants to enable WeChat message delivery—generate QR, have them scan, then connect
WeChat connection dropped and needs re-establishment—scan fresh QR and reconnect with new token
Verify whether WeChat is currently bound before attempting to send messages
User requests to unlink their WeChat account from the agent

Who it's for

Agents managing multi-channel messaging
Support workflows requiring WeChat integration
Users setting up or troubleshooting WeChat delivery

wechat-binding FAQ

Should I auto-poll qrcode_status after generating a QR?

No. Wait for the user to explicitly confirm they scanned and confirmed in WeChat first. Auto-polling spams the upstream API.

What is the difference between connect and reconnect?

Use connect for first-time binding (user has never bound this WeChat before). Use reconnect when the user was previously connected, the session dropped, and they just scanned a fresh QR. Call status first if unsure.

Can I show the WeChat QR code to a user on the WeChat channel itself?

No—they are trying to bind WeChat in the first place. Direct them to open the web app or use Telegram to scan the QR.

What should I do with the bot_token after qrcode_status returns it?

Immediately pass it to connect or reconnect. Never paste or echo the bot_token back to the user—it is a credential.

How do I check if WeChat is currently connected?

Call wechat(action="status") to see the current connection state before attempting to reconnect or send messages.

Full instructions (SKILL.md)

Source of truth, from starchild-ai-agent/official-skills.

name: wechat-binding version: 1.0.1 description: | 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). 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.

Typical binding flow

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

Generate QR: wechat(action="qrcode") — saves an image to workspace, returns qrcode (id) + file_path.
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.
Wait for the user to scan + confirm in WeChat. Don't auto-poll — let them say "scanned" / "done" first.
Poll for completion: wechat(action="qrcode_status", qrcode=<id from step 1>). Returns bot_token once scan + confirm completes.
Connect: wechat(action="connect", bot_token=<from step 4>). Optional: ilink_bot_id, ilink_user_id if the user has multiple WeChat accounts.
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.