WeChat Channel
Overview
The WeChat channel connects a WeChat Official Account so followers who message it land in the Team Inbox next to your other channels. WeChat is essential for reaching customers in mainland China, and it runs the same auto-reply, flows, AI agent and broadcasts as the rest of WaDesk, plus WeChat’s own custom menu and template messages.
WeChat is the strictest channel to set up. Registration requires a verified business entity, and several capabilities (customer-service messages, template messages, mass sends) are only available to Verified Service Accounts. Read Account Types before you start — picking the wrong type is the most common reason a WeChat rollout stalls.
Account Types — Choose Correctly
| Type | What you get |
|---|---|
| Subscription Account | Appears in a folder, good for publishing. No customer-service messaging API — two-way chat will not work. |
| Service Account (unverified) | Appears in the main chat list, but the messaging APIs stay locked until verification. |
| Service Account (Verified) | What you want. Full Messaging API: customer-service replies inside the 48-hour window, template messages, custom menus and mass sends. |
Verification is an annual paid review by Tencent and needs a business licence. An overseas entity can register a China-facing account through WeChat’s international flow, though the requirements differ by region.
How the Channel Works
- WeChat pushes inbound events to your server as XML over HTTP — not JSON like most platforms.
- Your server is authenticated to WeChat with an access token that WaDesk derives from your AppID and AppSecret and refreshes automatically before it expires.
- Inbound deliveries are verified with the Token you choose, and — in safe mode — decrypted with the EncodingAESKey.
- People reach you by following your Official Account, usually by scanning its QR code.
Registering & Getting Your Credentials
All four values come from the WeChat Official Accounts Platform. Step by step:
- Register the account. Go to mp.weixin.qq.com and register a Service Account, then complete verification. (International applicants start at admin.wechat.com.)
- Open Basic Configuration. Sign in to the console and go to Settings and Development → Basic Configuration (设置与开发 → 基本配置).
- Copy the AppID. It is shown as Developer ID (AppID).
- Generate the AppSecret. Next to Developer Password (AppSecret) click Generate / Reset. It is shown once — copy it immediately.
- Choose your own Token. In the Server Configuration block, invent a Token — any 3–32 character alphanumeric string. This is a shared password between WeChat and WaDesk; you will paste the same value into both.
- Generate the EncodingAESKey. Click Randomly generate to produce the 43-character key, and set Message encryption method to Safe mode (安全模式) — recommended, and supported by WaDesk.
- Allowlist your server IP. Under Security Center → IP allowlist, add your WaDesk server’s public IP address. WeChat refuses API calls from any other address.
The AppSecret is shown only once. If you lose it you must reset it, which immediately invalidates the old one and briefly breaks any live integration until you paste the new value into WaDesk.
Connecting in WaDesk
- Open the WeChat page — Channels → WeChat in the menu.
- Paste all four values — AppID, AppSecret, Token and EncodingAESKey — then save.
- Copy the server URL WaDesk shows you. It looks like
https://your-domain.com/api/wechat/inbound/<token>. - Paste it into WeChat. Back in Basic Configuration → Server Configuration, set Server address (URL) to that value, enter the same Token, paste the EncodingAESKey, choose Safe mode, and click Submit. WeChat immediately calls the URL to verify it — WaDesk answers the echo automatically.
- Enable the server. After a successful submit, click Enable (启用) on the Server Configuration block.
- Test it. Follow your Official Account with the WeChat app, send it a message, and watch it arrive in the Team Inbox.
Order matters. Save in WaDesk first, then submit in WeChat. WeChat verifies the URL the moment you press Submit, and it can only succeed if WaDesk already knows the Token.
API Limits & Rules
| Rule | What it means |
|---|---|
| 48-hour service window | You may send free-form customer-service replies for 48 hours after the user’s last message. After that only template messages are allowed. WaDesk shows the remaining window on the thread. |
| Template messages | The only way to message a follower outside the window. Templates are chosen from WeChat’s library or applied for, and approved by Tencent before use. |
| Mass send limits | A Verified Service Account may mass-send roughly 4 times per month to all followers. This is a WeChat platform rule, not a WaDesk one — plan your sends. |
| Follower required | You cannot message someone who has not followed the account. There is no cold outreach. |
| IP allowlist | API calls only work from allowlisted IPs. If your server moves or you add a node, update the allowlist or every send fails. |
| Access token sharing | WeChat issues one access token per account. Running another tool that fetches its own token will invalidate WaDesk’s and cause intermittent failures. |
Using the Inbox
- One thread per follower. Each WeChat user who messages the account gets a thread with their nickname and avatar.
- Media. Images, voice, video, files and location messages render inline.
- Window countdown. The thread shows how much of the 48-hour service window is left, so agents know when a free-form reply will still land.
Custom Menu
The custom menu is the bar at the bottom of your Official Account chat, with up to three top-level items and five sub-items each. Build it in Channels → WeChat → Menu and point each entry at a reply, a URL or a flow, then publish. WeChat can take a few minutes to show a menu change, and users may need to unfollow/refollow to see it immediately.
Auto-Reply, Flows & AI
- Auto-reply. Scope Welcome / Away / Out-of-hours / Keyword rules to your WeChat account in Auto Reply.
- Flows. Set the Trigger node’s channel to WeChat in the Flow Builder. Message, media, question and condition steps run on WeChat within the 48-hour window.
- AI agent. Assign an agent for automatic replies with hand-off to a human.
WeChat Broadcasts
The broadcast composer uses WeChat’s mass send API to reach all followers, or a tag-filtered subset. Because WeChat caps mass sends at roughly four per month, WaDesk shows the composer with that limit in mind — treat each one as a newsletter, not a routine push. Sends outside the 48-hour window to individuals must use an approved template message instead.
Troubleshooting
| Symptom | Cause & fix |
|---|---|
| “Token verification failed” on Submit | The Token in WeChat and in WaDesk differ, the URL has a typo, or you submitted before saving in WaDesk. Save in WaDesk first, then re-submit. |
| URL unreachable | WeChat requires a publicly reachable server on port 80/443. An IP address, a non-standard port or an unreachable host all fail. |
| Sends fail with an IP error (40164) | Your server IP is not in the WeChat IP allowlist. Add it under Security Center. |
| Intermittent “invalid credential” (40001) | Another system is fetching an access token for the same AppID and invalidating WaDesk’s. Use one integration per Official Account. |
| Two-way chat does nothing | You have a Subscription Account, or an unverified Service Account. The messaging APIs need a Verified Service Account. |
| Reply rejected after a day | The 48-hour service window closed. Use an approved template message. |