Skip to main content

WeChat

WeChat is China’s super-app. Orbit’s WeChat channel wraps the WeChat Official Account template-message API so you can deliver pre-approved template messages to your followers from the same unified Messaging surface used for every other channel.
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’s openid. 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 with POST /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.

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

Pass scheduled_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 returns 502 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:
The full error-recovery matrix sits under Common errors; the general retry/backoff pattern for the whole API is in Error handling by example.

Send at scale via campaign

To broadcast the same approved template to a whole audience, submit a campaign with channel 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.
Recipients without a connected 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 direct POST /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.
  1. Register a WeChat Official Account and create your template messages in the WeChat OA admin console. Each approved template receives a template id.
  2. 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.
  3. 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’s settings.channels.wechat and never echoes it back through any API response.
Per-organization credentials take precedence; when an organization has none, sends fall through to the platform default below.

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 with CHANNEL_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 standard message.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:
Verify signatures on every inbound event — worked examples in Verify webhook signatures.

Common errors

Pricing

WeChat Official Account messaging is governed by WeChat’s own template and quota rules. Orbit charges a flat per-1M platform fee for delivery and inbound webhook fan-in. See the pricing page.