​

Template-only Asia channels: the send playbook

​

1. Which channels demand a template

​

2. Decision tree: one body, swap the channel

1. Recipient is a phone number (E.164 digits), template lives on Zalo? → /messages/zalo.
2. Recipient is a phone number, template lives on KakaoTalk, any recipient (follower or not)? → /messages/kakao with an approved Alimtalk code (via a campaign — see §5), or with metadata.kakao_message_type: "friendtalk" plus a body when the recipient added your channel as a friend.
3. Recipient is a WeChat openid captured from an inbound follow? → /messages/wechat.
4. You hold no approved template at all → you are on the wrong channel; switch to LINE or Telegram and send a free-form body, or get a template approved first.

for ch in wechat zalo; do
  curl -s -X POST "https://api.orbit.devotel.io/api/v1/messages/${ch}" \
    -H "X-API-Key: ${ORBIT_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "84901234567",
      "template_name": "booking_confirmation",
      "template_params": { "name": "Linh", "code": "VN-4821" }
    }'
done

curl -X POST https://api.orbit.devotel.io/api/v1/messages/kakao \
  -H "X-API-Key: ${ORBIT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "821012345678",
    "body": "Your order has shipped.",
    "metadata": { "kakao_message_type": "friendtalk" }
  }'

​

3. Why a template send returns 422

• 422 VALIDATION_ERROR with no template_name — ZNS and OA messaging are template-only, so a body-only send is refused at the API. This is the optimistic gate: the 422 carries no provider round trip, so it costs nothing and returns immediately.
• CHANNEL_NOT_CONFIGURED (503) — the channel has no connected credentials and no platform default; fix this first, template questions come after.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Zalo ZNS is template-only — an approved templateName (template_id) is required"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "KakaoTalk Alimtalk is template-only — an approved templateName (templateCode) is required"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "WeChat template message requires an approved templateName (template_id)"
  }
}

​

4. One receiver for all inbound traffic

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/orbit', (req, res) => {
  const event = req.body;
  if (event.type !== 'message.received') return res.sendStatus(200);

  const { channel, message_id, from, body } = event.data;
  switch (channel) {
    case 'wechat':
    case 'zalo':
    case 'kakao':
    case 'line':
    case 'telegram':
      // One queue for all Asia inbound; branch further only if you must.
      console.log(`inbound ${channel} from ${from}: ${body}`);
      break;
    default:
      console.log(`inbound on channel ${channel} — extend the switch as you add channels`);
  }
  res.sendStatus(200);
});

from flask import Flask, request, jsonify

app = Flask(__name__)

ASIA_CHANNELS = {"wechat", "zalo", "kakao", "line", "telegram"}

@app.post("/webhooks/orbit")
def handle():
    event = request.get_json(force=True)
    if event.get("type") != "message.received":
        return jsonify(ok=True), 200
    data = event["data"]
    if data.get("channel") in ASIA_CHANNELS:
        print(f"inbound {data['channel']} from {data.get('from')}: {data.get('body')}")
    return jsonify(ok=True), 200

​

5. Bulk send via campaigns

curl -X POST https://api.orbit.devotel.io/api/v1/campaigns \
  -H "X-API-Key: ${ORBIT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Booking confirmations — ZNS",
    "channel": "zalo",
    "type": "blast",
    "audience_type": "all",
    "message_template": "booking_confirmation",
    "variables": { "name": "Linh", "code": "VN-4821" }
  }'

​

6. Per-channel references

• Zalo — ZNS templates, E.164 recipients
• WeChat — OA templates, openid recipients, optional metadata.url deep-link
• KakaoTalk — Alimtalk vs Friendtalk, message-type metadata
• LINE — free-form bodies, profile sender
• Telegram — free-form bodies