​

WeChat Onboarding: Official Account to Template Send

​

1. Prerequisites: Official Account and access token

1. Register a WeChat Official Account in your organization. Any account type (service or subscription) can send template messages if it is verified by WeChat — unverified accounts cannot select template message functions.
2. Generate an access token through the WeChat token grant. The token is short-lived (about two hours); WeChat returns errcode 40001 the moment it expires. Because the token rotates this quickly, plan for a central refresh — see Credential rotation below.

3. In the Orbit dashboard, open Settings → Channels → WeChat and paste the access token. Orbit stores it encrypted at rest and masks it after submit; it never appears in an API response.

​

2. Pick and approve a template

• In the WeChat Official Account admin console, choose a template from the library (or submit your own) and wait for WeChat’s approval. Each approved template gets a template id — that id is what you pass as template_name.
• Each template declares named placeholders in the {{key.DATA}} shape: {{order_id.DATA}}, {{carrier.DATA}}. Your template_params object is a flat string-to-string map keyed by those placeholder names, without the {{...}} plumbing — { "order_id": "A1024", "carrier": "SF Express" }.

​

3. Send your first template message

curl -X POST https://api.orbit.devotel.io/api/v1/messages/wechat \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "oABCdef1234567890ghijklmno",
    "template_name": "ORDER_SHIPPED_V2",
    "template_params": { "order_id": "A1024", "carrier": "SF Express" },
    "metadata": { "url": "https://h5.example.com/orders/A1024" }
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const message = await orbit.request("POST", "/messages/wechat", {
  to: "oABCdef1234567890ghijklmno",
  template_name: "ORDER_SHIPPED_V2",
  template_params: { order_id: "A1024", carrier: "SF Express" },
  metadata: { url: "https://h5.example.com/orders/A1024" },
});

console.log(message.data.status); // 'queued'

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

message = client.request(
    "POST",
    "/messages/wechat",
    json_body={
        "to": "oABCdef1234567890ghijklmno",
        "template_name": "ORDER_SHIPPED_V2",
        "template_params": {"order_id": "A1024", "carrier": "SF Express"},
        "metadata": {"url": "https://h5.example.com/orders/A1024"},
    },
)

print(message["data"]["status"])  # 'queued'

​

4. OpenID targeting and metadata.url deep links

• to is the follower’s openid. The openid is scoped to your Official Account — it is not the user’s WeChat id, and it is not portable to another OA. Followers hand it to you when they contact you: every inbound reply carries the sender’s openid on the message.received webhook (event.data.from), so store it on the contact record and reuse it for outbound targeting. A send to a string that is not a follower of your OA comes back from WeChat as errcode 40003 — do not retry those; the recipient is not addressable.
• metadata.url deep-links the message. Set it to an H5 page and the follower taps the rendered template message straight into it — order details, a booking page, a claim form. metadata is echoed back on the delivery and inbound webhooks, so you can reconcile your own identifiers end to end.

​

5. Inbound: replies and signature verification (optional)

• message.received with channel: "wechat" — a follower reply. The sender’s openid sits under event.data.from.
• message.status with channel: "wechat" — the delivery callback advancing your outbound message to its terminal delivered / failed state.

​

6. Credential rotation and errors you will actually see

• Rotate centrally and before expiry. Refresh the token through the WeChat grant, then paste the new value under Settings → Channels → WeChat. While an expired token sits connected, sends fail with errcode 40001 until the fresh one lands.
• Never commit a token to git, and scope each environment to its own Official Account so a leaked dev token cannot reach customer traffic.

​

Compliance notes

​

Where to go next

• WeChat channel page — full field reference, scheduling semantics, campaign broadcasting, and the pricing note.
• APAC channels onboarding — the same playbook for LINE, KakaoTalk, and Zalo, with a channel-picker per region.
• Fallback chains — position WeChat as a last-hop fallback to SMS or vice versa.
• Inbox setup — route inbound WeChat replies to your team.