WeChat earns its own operator guide. The APAC channel guide covers WeChat in one paragraph alongside LINE, KakaoTalk, and Zalo — enough to place it on the regional map, not enough to run it. A Chinese-market sender hits three constraints no other APAC channel combines: template-only sends, an Official Account verification regime with its own lifecycle, and an inbound contract where the follower's OA-scoped openid is the only address you will ever get. This guide walks the channel end to end on Devotel Orbit: anatomy, account scope, setup, inbound normalization, channel selection, fallback discipline, and the verification-and-review loop. The field-level contract stays in the WeChat channel reference; this post is the operating layer on top of it.
Channel anatomy: Official Account plus template-only sends
Two facts shape everything downstream.
The sender is a WeChat Official Account (OA). Your brand's presence is the OA, and your audience is its followers. There is no phone number in the targeting path: every send addresses a follower's openid, the OA-scoped identifier WeChat issues per user per account. The same person holds a different openid for every OA they follow, so an openid is meaningful only to the account that owns it — store it on the contact as a WeChat-specific identifier, never as a portable one.
Every send is a template message. WeChat OA messaging is template-only: template_name selects the approved template id and template_params fills the template's named {{key.DATA}} placeholders. A send without an approved template_name is rejected with VALIDATION_ERROR (422) before it leaves Orbit. There is no free-form outbound shape on this channel. The one outbound flourish is metadata.url, an optional H5 deep-link the follower can tap through from the rendered template.
Because the OA you connected is always the sender, the request carries no sender field and no credential — POST /api/v1/messages/wechat takes the recipient openid, the template pair, and scheduling metadata, and returns 202 Accepted with the message id. The terminal delivered / failed state arrives later on the delivery-status webhook, driven by WeChat's TEMPLATESENDJOBFINISH callback. Direct sends are capped at 80 requests/minute per organization; staged volume belongs on the campaigns API with channel: "wechat".
WeChat Work vs consumer WeChat: pick the scope first
Two products share the WeChat name, and they are different channels with different audiences:
- Consumer WeChat Official Account — the scope this guide and this channel cover. Your audience is the general WeChat user who chose to follow your OA. Template messages are service notifications: order updates, appointment reminders, delivery events, account alerts to people who opted in by following.
- WeChat Work (WeCom) — the enterprise messenger for internal employees and, through connected customers, a closed B2B audience. It has its own app, its own API, and its own compliance posture. It is not what
channel: "wechat"sends on.
If your use case is employee notifications inside a Chinese enterprise, WeChat Work is the scope to evaluate separately. If your use case is reaching consumers — a retailer's order updates, a travel brand's itinerary alerts, a financial service's transaction notices — the consumer OA path is the one, and the rest of this guide applies.
Setup checklist
The channel is bring-your-own-credential: you own the Official Account, Orbit delivers through it. In order:
- [ ] A verified WeChat Official Account. Register the OA in the WeChat OA admin console as a service account — subscription accounts do not qualify for template messaging. Verification is a first-class gate; it is also the tier that unlocks the template-message API surface.
- [ ] Approved template ids. Create each template in the OA admin console and wait out the approval cycle. Every approved template returns the id you will pass as
template_name. Template idioms are conservative — order, appointment, delivery, account-notification shapes — so model your messages on what the category expects before you submit. - [ ] An OA access token. Obtain the token via the WeChat token grant. It is a bearer credential and it is short-lived (roughly two hours); whoever holds it can send as your Official Account, so keep it out of git, CI logs, and screenshots, and scope each environment to its own OA.
- [ ] The credential pair connected in Orbit. Under Settings → Channels → WeChat, paste the access token (the pair is the token plus the OA it belongs to). Orbit stores it encrypted at rest per organization and never returns it through any API response. No token ever travels on a send request — the endpoint resolves the sender from what you connected.
- [ ] A rotation runbook. Because the token expires on a WeChat clock, a send can fail mid-program with
MESSAGE_SEND_FAILED(502) carrying an expired-token provider code. Refresh through the WeChat grant, re-paste under Settings → Channels → WeChat, and retry once. Two other provider codes deserve a different response: an unknown-openidfailure means the recipient is not a follower — stop retrying and fall back — and an invalid-template-id failure means the template id, not the recipient, is wrong. - [ ] Tenant-owned messaging policy. Consent capture, quiet hours, and opt-out handling are yours to define for your jurisdictions; Orbit enforces the tenant-configured controls the same way it does on every other channel.
WeChat is a beta channel: the send and receive paths are wired end to end, and the OA provisioning above is the onboarding work the beta label stands for.
The inbound envelope: channel: "wechat"
Inbound is the part operators underestimate. There is no WeChat webhook for you to register: inbound replies and delivery receipts are normalized by Orbit's messaging gateway and relayed to your account automatically.
Replies arrive on the standard message.received webhook with channel: "wechat". The envelope carries the follower's openid in from, the reply text in body, and any send-time metadata echoed back. Status advances arrive on message.status with the same channel tag and the terminal state under status. Subscribe to both under Settings → Webhooks and verify signatures on every event.
One operand discipline: an inbound openid is precious because it is the only way to target that follower back. Write it to the contact record on first touch, so the follow-up send — and the shared-inbox agent who answers the reply — addresses a known recipient rather than an anonymous id. Inbound replies land in the same omnichannel inbox as WhatsApp, LINE, and SMS, routed by the same tenant-level rules.
When WeChat wins — and when the sibling channels carry it
The market decides first. A sender with real volume in mainland China has no substitute: LINE does not operate there, KakaoTalk and Zalo are regional elsewhere, and WhatsApp is absent. WeChat is the channel. The APAC channel guide lays out the full regional map; the OTT channel survey covers the wider beyond-SMS field. The short decision table:
| Your market | First channel | Why |
|---|---|---|
| Mainland China | WeChat OA | The universal app; no viable substitute at scale |
| Japan, Thailand, Taiwan | LINE | Template-free sends and the dominant regional app — see the LINE reference |
| Korea | KakaoTalk | Alimtalk for transactional reach, Friendtalk to followers |
| Vietnam | Zalo | ZNS template notifications on the national app |
WeChat also wins on audience depth rather than geography: a brand whose Chinese-market customers already follow its OA should serve them there even when SMS technically reaches them, because the template message renders inside the app the customer opens first. The trade it demands is the template regime — if your program needs free-form outbound copy approved on the fly, LINE's template-free sends or a WhatsApp template pair carry that load better.
Fallback discipline: SMS under WeChat, diaspora handled separately
Two fallback postures, per audience:
In-country China traffic. Configure an org-level chain, WeChat → SMS, for the transactional classes that cannot wait: OTPs, delivery events, appointment reminders. When a send fails because the recipient is not a follower — the unknown-openid provider code — the chain absorbs the gap without your code retrying. The SMS leg exits through Devotel's own wholesale network, so the fallback hop adds no resold aggregator in the path. Keep marketing classes out of the chain; a service notification that degrades to SMS is a recovery, a promotion that does is a complaint vector.
The EU (and wider) Chinese diaspora. A Chinese-speaking customer in Berlin or Amsterdam is not a WeChat OA reach problem — they are a WhatsApp, RCS, and SMS audience with a language preference. Do not stretch the WeChat channel across that gap: address diaspora segments on the channels that deliver there, set the language on the contact, and keep WeChat for the audience segment that actually lives on consumer WeChat. The org-level chain is the fallback surface for both postures; the cross-channel fallback concept documents how each hop bills and re-checks its compliance gates independently.
Verification, review, and cost
Three recurring loops keep the channel healthy:
- OA verification tier. WeChat re-reviews verified accounts on its own cycle. Treat the OA's verification status as a monitored dependency — a lapsed verification halts template messaging regardless of anything on Orbit's side.
- Template review loop. New templates and materially changed ones go back through WeChat approval. Build the approval latency into campaign planning and keep a handback discipline with whoever owns template idiom on your team: the operator names the variables, the WeChat-side owner submits, and only the approved id ships as
template_name. - Cost structure. WeChat governs its own template and quota rules; Orbit charges a flat per-1M platform fee for delivery and inbound webhook fan-in. Per-message cost then decomposes to the platform fee plus whatever program-level review time your template churn costs — a template-heavy catalog pays approval latency many times, which is an operating cost even when it is not an invoice line.
Frequently asked questions
Can I send free-form text on the WeChat channel?
No. WeChat OA messaging is template-only: every send carries an approved template_name and the template_params that fill its placeholders. A send without one is rejected with VALIDATION_ERROR (422).
What identifier do I send to?
The follower's openid — the OA-scoped id WeChat issues per user per Official Account. Capture it from inbound message.received events and store it on the contact; it is the only targeting key the channel accepts.
Does WeChat Work (WeCom) use this channel?
No. This channel covers the consumer WeChat Official Account scope. WeChat Work is the enterprise messenger with its own API and audience; evaluate it as a separate scope.
What happens when the OA access token expires?
Sends start returning MESSAGE_SEND_FAILED (502) with the expired-token provider code embedded in the error message. Refresh the token through the WeChat grant, re-paste it under Settings → Channels → WeChat, and retry. Rotation is routine — the token lifetime is roughly two hours — so automate or calendar it.
Is there a webhook to register with WeChat?
No. Inbound replies and delivery receipts are normalized by Orbit and relayed automatically. Replies arrive on message.received with channel: "wechat"; terminal states arrive on message.status. Subscribe under Settings → Webhooks.
How does WeChat pricing work?
WeChat's own template and quota rules govern the channel; Orbit charges a flat per-1M platform fee for delivery and inbound webhook fan-in. The current figures are on the pricing page.
Source and further reading
- WeChat channel reference: the field-level send/receive contract this guide operates — request body, error matrix, campaign shape, rate limits, and the credential-connect steps in full.
- Messaging in APAC: LINE, WeChat, KakaoTalk, and Zalo: the four-channel regional bundle this post zooms out of.
- Beyond SMS: WhatsApp and the OTT channels: the wider OTT survey, for where WeChat sits among the non-SMS field.
- Cross-channel fallback: the org-level chain model behind the WeChat → SMS fallback posture.
Published 28 September 2026.