​

Zalo onboarding: connect your Official Account and send ZNS templates

​

1. Prerequisites: Official Account and consent

1. Create a Zalo Official Account (OA) in the Zalo for Developers console. The OA is the sender identity on every ZNS notification.
2. Register your ZNS templates in the same console and wait for Zalo approval. Each approved template receives a template id — that id is what template_name references on a send. An edited template is a new approval.
3. Generate the OA access token (OAuth oauth/access_token grant) and paste it in Orbit under Settings → Channels → Zalo. The token is short-lived; rotate it through Zalo’s grant before it expires. Orbit stores it encrypted at rest and never echoes it back through any API response.

​

2. Template-based send — no free-form body

curl -X POST https://api.orbit.devotel.io/api/v1/messages/zalo \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "84901234567",
    "template_name": "booking_confirmation",
    "template_params": { "name": "Linh", "code": "VN-4821" },
    "metadata": { "order_id": "VN-4821" }
  }'

​

3. Samples: curl, Node.js, Python

curl -X POST https://api.orbit.devotel.io/api/v1/messages/zalo \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "84901234567",
    "template_name": "booking_confirmation",
    "template_params": { "name": "Linh", "code": "VN-4821" }
  }'

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

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

// The Node SDK has no typed sendZalo method yet — reach the route
// through the generic request() escape hatch.
const { data } = await orbit.request("POST", "/messages/zalo", {
  to: "84901234567",
  template_name: "booking_confirmation",
  template_params: { name: "Linh", code: "VN-4821" },
});

console.log(data.id);     // msg_9f2c1e...
console.log(data.status); // 'queued'

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

# No typed Zalo helper either — the escape hatch takes a json_body.
res = client.request(
    "POST",
    "/messages/zalo",
    json_body={
        "to": "84901234567",
        "template_name": "booking_confirmation",
        "template_params": {"name": "Linh", "code": "VN-4821"},
    },
)
print(res["data"]["id"])      # msg_9f2c1e...
print(res["data"]["status"])  # 'queued'

​

4. Inbound replies and delivery statuses

• Inbound replies arrive on message.received with channel: "zalo", folded onto the normalized inbound event envelope. Branch on data.normalized.kind === "inbound" instead of parsing event strings.
• Delivery status advances the outbound message to delivered / failed, reconciled by the tracking id Orbit mints per send. Your metadata map rides along on the event.

app.post('/webhooks/orbit', (req, res) => {
  // Verify the X-Orbit-Signature header first — see the signature guide below.
  const event = req.body;
  if (event.type === 'message.received' && event.data.channel === 'zalo') {
    if (event.data.normalized.kind === 'inbound') {
      console.log(`Zalo reply from ${event.data.from}: ${event.data.body}`);
    }
  }
  res.sendStatus(200); // Orbit keeps retrying until you 2xx.
});

​

5. Common errors

​

See also

• Zalo channel page — field reference, error codes, and credential handling.
• APAC channels onboarding — LINE, WeChat, KakaoTalk, and Zalo in one survey.
• Template-only Asia channels playbook — one approved template across every template channel.
• Campaigns API — bulk template sends.
• Message suppression — per-recipient opt-out handling.