WeChat is a beta channel. The send and receive paths are wired end to end, but onboarding still requires you to provision a WeChat Official Account and a valid OA access token.
How OA template messages work
WeChat Official Account messaging is template-only: you send a pre-approved template message to a follower’sopenid. template_name selects the approved template id and template_params fills the template’s named {{key.DATA}} placeholders. An optional metadata.url deep-links the message to an H5 page. A send without an approved template_name is rejected with VALIDATION_ERROR (422).
Send a WeChat message
Send a single WeChat OA template message withPOST /api/v1/messages/wechat — the direct per-message endpoint, the same shape as every other channel’s send route (/sms, /line, /zalo). Select the approved template with template_name and fill its {{key.DATA}} placeholders with template_params.
- curl
- Node.js
- Python
- Go
Request body
The sender is selected automatically from the WeChat Official Account credentials connected to your organization — you do not pass an access token on the request.
Response
202 Accepted — the message is persisted and queued for delivery; the terminal delivered / failed state arrives later via the delivery-status webhook.
Schedule a send
Passscheduled_at as an RFC 3339 timestamp to defer dispatch — the message sits as scheduled until the wall-clock time, then queues. Pull it back with PATCH /messages/:id or cancel it with DELETE /messages/:id any time before dispatch. Full scheduling semantics: Message scheduling.
Handle a send failure
When WeChat rejects the send, the API returns502 with error.code set to MESSAGE_SEND_FAILED and the upstream WeChat errcode embedded in error.message. Every non-zero errcode is not the same failure — 40001 is an expired access token (rotate your credential), 40003 is an unknown openid (stop retrying, the recipient is not a follower), 40037 names an invalid template id. Read the code and branch:
Send at scale via campaign
To broadcast the same approved template to a whole audience, submit a campaign withchannel set to wechat — one campaign call replaces a loop over the single-send endpoint, and the same OA credentials, template_name, and template_params shape apply. The campaign accepts a segment as its audience, and every recipient message inherits the template payload the campaign carries.
openid are skipped per send; use the campaign dashboard row’s per-contact status to reconcile. For more template-message patterns, see Publish a template and send it — task 13 runs the same shape on WhatsApp.
Rate limits
The directPOST /messages/wechat endpoint is capped at 80 requests/minute per organization. Bursts above the cap receive 429 with a Retry-After header; back off and retry, or stage high-volume sends through the campaigns API. See Rate Limits.
Configuration
WeChat is a bring-your-own-credential channel. You can connect it per organization in the dashboard, or set a platform-default credential for the whole cluster.Per organization (recommended)
- Register a WeChat Official Account and create your template messages in the WeChat OA admin console. Each approved template receives a template id.
- Obtain the OA access token via the
cgi-bin/token(or stable-token) grant. The token is short-lived (~2 hours); rotate it centrally before it expires. - In the Orbit dashboard, go to Settings → Channels → WeChat and paste the access token. Orbit stores it encrypted at rest (
enc:v1:envelope) under your organization’ssettings.channels.wechatand never echoes it back through any API response.
Platform default
An operator can register a single cluster-wide WeChat provider by setting one environment variable. When it is unset the channel stays unregistered and a send fails closed withCHANNEL_NOT_CONFIGURED.
Credential handling — your responsibility
The OA access token is a bearer credential. Anyone holding it can send messages as your Official Account. Orbit encrypts it at rest and masks it in the dashboard after submit, but its safety upstream of Orbit (your password manager, CI/CD variables, screenshots) is yours to protect:- Never commit an access token to git, public or private.
- Rotate immediately through the WeChat grant if you suspect exposure, then re-paste the new value in Orbit.
- Scope each environment to its own Official Account so a leaked dev token cannot reach customer conversations.
Receive inbound replies
Inbound replies and delivery receipts are normalized by the Orbit messaging gateway and relayed to your account automatically — there is no WeChat webhook for you to register. Replies arrive on the standardmessage.received webhook with channel: "wechat"; WeChat’s TEMPLATESENDJOBFINISH callback advances your outbound message to delivered / failed. Subscribe to these under Settings → Webhooks.
Both snippets below read the normalized envelope, filter the WeChat lane, and hand the reply off to your own handling: