> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# APAC channels onboarding: LINE and WeChat

> Step-by-step onboarding playbook for LINE and WeChat — connect channel credentials, send template-free and template-only messages, route inbound events, pick the right channel per region, and read the error codes you will actually see.

# APAC channels onboarding: LINE and WeChat

This guide walks you end to end through the APAC-region channels — LINE (Japan, Thailand, Taiwan) and WeChat (China) — from first credential connect through send, inbound webhook, and error handling. KakaoTalk (Korea) and Zalo (Vietnam) follow the same shape with channel-specific quirks; the fold-in notes below cover them.

The guide complements the per-channel references ([LINE](/channels/line), [WeChat](/channels/wechat), [KakaoTalk](/channels/kakao), [Zalo](/channels/zalo)) — those document the API shapes; this guide is the ordered playbook you follow the first time.

## Pick the right channel per region

Do not activate every APAC channel at once. Pick one:

* **LINE** — the right default in Japan, Thailand, and Taiwan. Dominant share in those markets.
* **WeChat** — China's super-app. Template-only Official Account messaging.
* **KakaoTalk** (Korea) — Alimtalk (template-only transactional) and Friendtalk (free-form to followers).
* **Zalo** (Vietnam) — template-only ZNS notifications.

If you are unsure, start with LINE unless your audience is Korea/China/Vietnam.

## 1. LINE — connect the channel

LINE is a bring-your-own-credential channel: you register a Messaging API channel with a LINE Official Account, then paste its token and secret into Orbit.

1. In the [LINE Developers Console](https://developers.line.biz/console/), create or open a **Messaging API channel** for your LINE Official Account.
2. From the channel's **Messaging API** tab, copy the long-lived **Channel access token**. From **Basic settings**, copy the **Channel secret**.
3. In Orbit, go to **Channels → LINE → Connect** and paste both values. Orbit stores them encrypted at rest under `settings.channels.line`.
4. Set the channel's **Webhook URL** in the LINE Developers Console to `https://api.orbit.devotel.io/api/v1/webhooks/inbound/line` and enable **Use webhook**. All tenants share this single URL — Orbit resolves the receiving tenant from the LINE channel id (`destination`) on each event.

The [credentials section of the LINE channel page](/channels/line#credential-handling--your-responsibility) covers rotation and the rule that the token must never sit in git.

## 2. LINE — send a template-free message

Ordinary text, image, video, sticker, flex, and location messages on LINE are **template-free** — you send a plain `body` and pick the `type` per message. (Template-only applies only to Zalo ZNS, WeChat, and KakaoTalk Alimtalk.)

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/line \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "U4af4980629...",
    "body": "Your order has shipped.",
    "type": "text"
  }'
```

| Field  | Required | Description                                                                                     |
| ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `to`   | yes      | Recipient LINE id — a user (`U…`), group (`C…`), or room (`R…`) id taken from an inbound event. |
| `body` | yes      | Message body, 1–5000 characters.                                                                |
| `type` | no       | `text`, `image`, `video`, `audio`, `location`, `sticker`, or `flex`. Defaults to `text`.        |

The sender is selected automatically from the connected channel credentials — you do not pass a token on the request. `202 Accepted` means queued; terminal `delivered` / `failed` arrives on the delivery-status webhook.

### Sender identity

LINE is a **profile** channel: your Official Account's name and avatar are the sender. There is no `sender_id` to pass per message — identity is bound to the channel you connected.

## 3. LINE — inbound and webhooks

Inbound user messages, follows, joins, and postbacks are POSTed to your registered webhook endpoint with the standard Orbit inbound envelope (`channel: "line"`). Every inbound carries the sender's LINE id — store it on the contact so replies reuse it.

Delivery-status callbacks (LINE `delivery` events) land separately on `/api/v1/webhooks/dlr/line`; Orbit wires them as part of connect — you do not register them yourself. Signature verification (HMAC-SHA256 against the stored `channel_secret`) is enforced before any event reaches your endpoint.

## 4. LINE — errors you will actually see

| Code                  | HTTP | Cause                                                                                         | Fix                                                                                             |
| --------------------- | ---- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `INVALID_RECIPIENT`   | 422  | `to` is empty or not a usable LINE id.                                                        | Send to a user (`U…`), group (`C…`), or room (`R…`) id captured from inbound.                   |
| `VALIDATION_ERROR`    | 422  | `to` or `body` missing; `body` > 5000 chars; a `flex` message's `flex_contents` invalid JSON. | Correct the request body and retry.                                                             |
| `MESSAGE_SEND_FAILED` | 502  | LINE rejected the push or was unreachable.                                                    | Check the failure reason on the status webhook; re-paste the token if it rotated.               |
| `RATE_LIMITED`        | 429  | > 80 sends/minute for the tenant.                                                             | Honour `Retry-After`; stage bulk sends through [Campaigns](/api-reference/endpoints/campaigns). |

`LINE_INVALID_TOKEN` (401) is raised only at connect time. A token rotated after connect surfaces as `MESSAGE_SEND_FAILED` until you re-paste the current token — see [LINE credential handling](/channels/line#credential-handling--your-responsibility).

## 5. WeChat — Official Account onboarding

WeChat is template-only: you cannot send free-form text to a follower. You must provision a WeChat Official Account, get your templates approved, and register its access token with Orbit.

1. Register a **WeChat Official Account** and create template messages in the WeChat OA admin console. Each approved template receives a template id.
2. Obtain the OA **access token** via the WeChat token grant. It is short-lived (\~2 hours); rotate it centrally before expiry.
3. In Orbit, go to **Settings → Channels → WeChat** and paste the access token. Orbit stores it encrypted at rest under `settings.channels.wechat`.

### When an external sender-id is needed

Ordinary template sends address the follower by `to` = their OA-scoped `openid` — no sender-id on the request. If a WeChat campaign you run needs a branded sender identity that is not the connected OA, that identity is bound to the OA at connect time (not per send) and is the OA's responsibility.

## 6. WeChat — template-only send

Send with `POST /api/v1/messages/wechat`. Select the approved template with `template_name` and fill its placeholders with `template_params`.

```bash theme={null}
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" }
  }'
```

A send without an approved `template_name` is rejected with `VALIDATION_ERROR` (422). For bulk sends, submit a [campaign](/api-reference/endpoints/campaigns) with `channel: "wechat"` rather than looping the single-send endpoint.

### Inbound and fallback

Inbound replies arrive on the standard `message.received` webhook with `channel: "wechat"`; WeChat's delivery callback advances your outbound message to `delivered` / `failed`. WeChat is deliberately positioned as the last-hop fallback to SMS when a WeChat send fails — see [Fallback chains](/guides/fallback-chains).

## 7. Folded-in channels (KakaoTalk, Zalo)

* **KakaoTalk** (Korea): two message types. **Alimtalk** — template-only, pre-approved template code, to any phone number. **Friendtalk** — free-form `body` text to users who added your channel as a friend. Select with `metadata.kakao_message_type`; details in the [KakaoTalk channel page](/channels/kakao).
* **Zalo** (Vietnam): template-only **ZNS** (Zalo Notification Service) messages — no free-form send shape. Details in the [Zalo channel page](/channels/zalo).

## Where to go next

* [Send and receive messages](/guides/send-receive-messages) — the cross-channel send pattern.
* [Inbox setup](/guides/inbox-setup) — route inbound APAC-channel traffic to your team.
* [Best practices](/guides/best-practices) — platform-wide sending hygiene.
* [LINE channel page](/channels/line) · [WeChat channel page](/channels/wechat) — per-channel API references.