LINE Onboarding: Messaging API Channel to Working Two-Way Chat

This guide walks you from an empty LINE channel to a working, production-ready setup. It complements the LINE channel page, which covers message shapes and capability detail — this guide is the ordered path you follow the first time, and re-run whenever you attach, rotate, or retire a LINE Official Account. LINE has no template approval cycle for plain text, and no brand gate beyond having a LINE Official Account. The real work is connecting the right credentials and understanding which LINE recipient ids are usable. The Asia channels onboarding guide positions LINE beside KakaoTalk, Viber, and WeChat; this guide is the LINE-specific walkthrough.

1. Prerequisites — the Messaging API channel

You need two things from a LINE Official Account before Orbit can carry traffic:

A LINE Official Account. If you do not have one, create it in the LINE Official Account Manager.
A Messaging API channel on that account, created in the LINE Developers Console.

From the channel you need two credentials — copy them once, because the console does not always show the secret again:

Channel access token (long-lived) — from the channel’s Messaging API tab. This is the bearer token LINE accepts on outbound push calls.
Channel secret — from the channel’s Basic settings tab. Orbit uses it to verify the x-line-signature header on inbound webhooks before any event reaches your handler.

Also copy the numeric channel id (from the Basic settings tab) — it is the destination value every inbound webhook carries, and it is what identifies your tenant on the shared inbound URL. Treat both values as bearer credentials: anyone holding them can message as your Official Account. See Credential handling — your responsibility on the channel page for the handling rules (never commit to git, scope dev/staging/production to separate channels, rotate on suspicion).

2. Connect the channel to Orbit

Paste the two values once in the dashboard:

Navigate to Channels → LINE → Connect.
Paste the channel access token and channel secret. Orbit validates the token at connect time — an expired or invalid token returns LINE_INVALID_TOKEN (401) instead of connecting.
Orbit stores both values encrypted at rest under your organization’s settings.channels.line and never echoes them back through any API response.
In the LINE Developers Console, set the channel’s Webhook URL to https://api.orbit.devotel.io/api/v1/webhooks/inbound/line and enable Use webhook. Every Orbit tenant shares this single URL — the LINE channel id (destination) on each inbound event is what resolves the receiving tenant (see §4).

Connect and disconnect are write-class operations — they require the owner, admin, or developer role. Where the connect-time rejection actually lands: the connect call answers 200 with a body that carries the rejection — branch on data.error_code, not on the HTTP status. An expired or invalid channel access token looks like this:

{
  "data": {
    "ok": false,
    "error_code": "LINE_INVALID_TOKEN",
    "error_message": "LINE rejected the stored credentials.",
    "error_status": 401
  },
  "meta": {
    "request_id": "req_2f81ac",
    "timestamp": "2026-09-02T08:12:44Z"
  }
}

error_status is the status LINE’s own API returned to Orbit’s verification probe. Re-paste a current token under Channels → LINE and connect again — a token rotated after a successful connect keeps working on sends until LINE rejects it, and that surfaces as MESSAGE_SEND_FAILED (§7).

3. Send — POST /api/v1/messages/line

Sending goes through the unified Messaging surface. The text body is the top-level body field, the LINE message type is the top-level type field (defaulting to text), and the per-type secondary options ride under metadata as string→string values. The sender is selected automatically from your connected channel credentials — you never pass a token or channel id on the request. The request body is the shared free-form shape used by the other OTT channels (Viber, Telegram, KakaoTalk) — to + body are the only required fields, with optional from, media_url, metadata, and scheduled_at:

Field	Required	Notes
`to`	yes	Recipient LINE id — a user id (`U…`), group id (`C…`), or room id (`R…`) — taken from an inbound event.
`body`	yes	Message body, 1–5000 characters.
`type`	no	One of `text`, `image`, `video`, `audio`, `location`, `sticker`, `flex`. Defaults to `text`.
`metadata`	no	Flat string→string map. Non-text types read their options here (see Request body on the channel page).

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": "Welcome! Reply with a number to continue.",
    "type": "text"
  }'

import { Devotel } from '@devotel-orbit/node';

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

// Fully-typed per-channel method — prefer it over the generic send.
// LINE accepts up to 5 stacked messages per push.
const message = await orbit.messages.sendLine({
  to: 'U4af4980629...',
  messages: [
    { type: 'text', text: 'Welcome! Reply with a number to continue.' },
  ],
});

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

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

# The Python SDK has no typed send_line method — reach the channel
# endpoint through the client.request escape hatch (raw JSON returned).
message = client.request(
    "POST",
    "/messages/line",
    json_body={
        "to": "U4af4980629...",
        "body": "Welcome! Reply with a number to continue.",
        "type": "text",
    },
)

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

package main

import (
    "context"
    "fmt"

    orbit "github.com/devotel/orbit-go/orbit"
)

// /messages/line sits below the Go SDK's typed surface — use the
// low-level request helper. Values in Metadata are strings only.
func main() {
    client := orbit.NewClientFromEnv() // reads ORBIT_API_KEY

    message, err := client.Request(context.Background(), "POST", "/messages/line", map[string]any{
        "to":   "U4af4980629...",
        "body": "Welcome! Reply with a number to continue.",
        "type": "text",
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(message["data"].(map[string]any)["id"])     // msg_line_abc123
    fmt.Println(message["data"].(map[string]any)["status"]) // queued
}

# /messages/line is below the typed surface — the raw escape hatch.
send = client.request(
    "POST",
    "/messages/line",
    json_body: {
        to: "U4af4980629...",
        body: "Welcome! Reply with a number to continue.",
        type: "text",
    },
)

puts send.dig("data", "id")       # msg_line_abc123
puts send.dig("data", "status")   # queued

// /messages/line is below the typed surface — the raw escape hatch.
$send = $client->request("POST", "/messages/line", [
    "to"   => "U4af4980629...",
    "body" => "Welcome! Reply with a number to continue.",
    "type" => "text",
]);

echo $send["data"]["id"];      // msg_line_abc123
echo $send["data"]["status"];  // queued

202 Accepted means queued — the terminal delivered / failed state arrives later on the delivery-status webhook, whose envelope shape is documented on the channel page. A soft failure (recipient blocked your Official Account) shows up there as message.failed with error_code: MESSAGE_DELIVERY_FAILED. Outbound POST /messages/line is capped at 80 requests/minute per tenant; bursts past the cap receive 429 with a Retry-After header, so stage high-volume sends through the campaigns API.

The full send with metadata — six languages

metadata is a flat string→string map, and that is the part first integrations get wrong: every value must already be a string. Send numbers as strings, and send nested JSON (like a flex layout) as a JSON-encoded string, never as a nested object. The same text send with a campaign_tag attached:

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": "Welcome! Reply with a number to continue.",
    "type": "text",
    "metadata": { "campaign_tag": "welcome_flow" }
  }'

import { Devotel } from '@devotel-orbit/node';

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

// sendLine's typed surface has no metadata, so the full shape — including
// metadata — goes through the escape hatch. Every metadata VALUE is a
// string; stringify anything richer before it lands here.
const message = await orbit.request<{
  data: { id: string; status: string };
}>('POST', '/messages/line', {
  to: 'U4af4980629...',
  body: 'Welcome! Reply with a number to continue.',
  type: 'text',
  metadata: { campaign_tag: 'welcome_flow' },
});

console.log(message.data.id);  // msg_line_abc123

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

# metadata values must be strings — quote numbers, and JSON-encode
# anything nested before you put it in the map.
message = client.request(
    "POST",
    "/messages/line",
    json_body={
        "to": "U4af4980629...",
        "body": "Welcome! Reply with a number to continue.",
        "type": "text",
        "metadata": {"campaign_tag": "welcome_flow"},
    },
)

print(message["data"]["id"])  # msg_line_abc123

// metadata is map[string]string — every value a string. A nested JSON
// payload (flex layouts, §3b) must be marshalled to a string first.
message, err := client.Request(context.Background(), "POST", "/messages/line", map[string]any{
    "to":   "U4af4980629...",
    "body": "Welcome! Reply with a number to continue.",
    "type": "text",
    "metadata": map[string]string{
        "campaign_tag": "welcome_flow",
    },
})

send = client.request(
    "POST",
    "/messages/line",
    json_body: {
        to: "U4af4980629...",
        body: "Welcome! Reply with a number to continue.",
        type: "text",
        # string→string map — quote every value, even numeric-looking ones.
        metadata: { campaign_tag: "welcome_flow" },
    },
)

$send = $client->request("POST", "/messages/line", [
    "to"   => "U4af4980629...",
    "body" => "Welcome! Reply with a number to continue.",
    "type" => "text",
    // string→string map: ["key" => "string"], never a nested array.
    "metadata" => ["campaign_tag" => "welcome_flow"],
]);

For text sends Orbit echoes metadata back on the delivery and status webhooks, so a tag set here is how you correlate a webhook to the send that caused it.

Sticker and flex messages

Two types cannot be deduced from the field table above, so here they are worked end to end. Sticker — a sticker message takes exactly two options: the sticker set (package_id) and the sticker inside it (sticker_id), both strings under metadata. body is required by the API but is not rendered by LINE; put a plain-text fallback in it for surfaces that cannot show the sticker.

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": "Thanks for joining!",
    "type": "sticker",
    "metadata": {
      "package_id": "446",
      "sticker_id": "1988"
    }
  }'

// Sticker ids are strings in metadata — never numbers.
const sticker = await orbit.request('POST', '/messages/line', {
  to: 'U4af4980629...',
  body: 'Thanks for joining!',
  type: 'sticker',
  metadata: {
    package_id: '446',
    sticker_id: '1988',
  },
});

Flex — a flex message carries the whole Flex layout as one JSON-encoded string under metadata.flex_contents. Encode it twice: build the layout object, then stringify it so it sits inside metadata as a single string value. The top-level body becomes LINE’s altText — the text announced where the layout cannot render, so write a real sentence, not a placeholder. A layout that is not a valid JSON object (an array, or malformed JSON) is rejected with VALIDATION_ERROR (422).

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 #2311 is out for delivery",
    "type": "flex",
    "metadata": {
      "flex_contents": "{\"type\":\"bubble\",\"body\":{\"type\":\"box\",\"layout\":\"vertical\",\"contents\":[{\"type\":\"text\",\"text\":\"Order #2311\"},{\"type\":\"text\",\"text\":\"Out for delivery — arriving today before 6 pm.\"}]}}"
    }
  }'

// Build the layout as an object, then stringify it ONCE so it rides
// metadata as a single string value; body becomes LINE's altText.
const layout = {
  type: 'bubble',
  body: {
    type: 'box',
    layout: 'vertical',
    contents: [
      { type: 'text', text: 'Order #2311' },
      { type: 'text', text: 'Out for delivery — arriving today before 6 pm.' },
    ],
  },
};

const flex = await orbit.request('POST', '/messages/line', {
  to: 'U4af4980629...',
  body: 'Your order #2311 is out for delivery',
  type: 'flex',
  metadata: { flex_contents: JSON.stringify(layout) },
});

The remaining types (image, video, audio, location) follow the same pattern — their option keys are listed on the channel page, and the API recipes cookbook works several of them through the shared OTT shape.

The response envelope

Every send above answers the same envelope; data.id is your handle for polling and reconciliation:

{
  "data": {
    "id": "msg_line_abc123",
    "status": "queued",
    "channel": "line"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-06-08T00:00:00Z"
  }
}

4. Inbound — tenant resolution from `destination`

LINE fans every tenant’s inbound traffic into the single platform URL you set in §2. Each inbound event carries a destination field — the numeric LINE channel id of the receiving Official Account — and Orbit resolves the owning tenant from that value before doing anything else:

Read the untrusted payload’s destination and resolve the tenant that connected that channel id.
Verify the x-line-signature HMAC-SHA256 header against that tenant’s stored channel secret. Requests that fail verification are rejected before any webhook fires.
Normalize each message-type event into the canonical inbound envelope and forward it to the endpoint configured under Settings → Webhooks, signed with the Standard-Webhooks scheme.

Because tenant resolution happens per-event, the shared URL is multi-tenant-safe: a misconfigured channel id cannot route traffic into a neighbor’s webhook chain. The raw payload LINE posts to the shared URL carries destination at the top level — the channel id you copied in §1. Here 1654385910 is what resolves the tenant; replyToken and source.userId are LINE’s own ids, and the U… user id is what you send replies to:

{
  "destination": "1654385910",
  "events": [
    {
      "type": "message",
      "message": { "id": "574238471923", "type": "text", "text": "Store hours?" },
      "replyToken": "0f36ae22e14c4dd7a1b8",
      "source": { "type": "user", "userId": "U4af4980629..." },
      "timestamp": 1756801872345
    }
  ]
}

After resolution and verification, your webhook receiver gets the normalized envelope — the same event, with destination resolved into your tenant:

{
  "id": "evt_9d4e2b8c1f",
  "type": "message.received",
  "created_at": "2026-09-02T08:31:12Z",
  "data": {
    "message_id": "msg_1n58gk",
    "channel": "line",
    "from": "U4af4980629...",
    "to": "1654385910",
    "body": "Store hours?",
    "provider_status": "inbound"
  }
}

Inbound user messages are the only events that reach your webhook receiver. Follows (joins), unfollows, postbacks (button taps), and reads arrive in the same verified payload, but the dispatcher acknowledges and drops them — if your flow must react to a button press, run it inside Orbit (flows, journeys), not in your receiver. The sender’s LINE id (U…) on the envelope is the to value for every outbound reply. Delivery receipts from LINE advance the outbound lifecycle on a separate POST /api/v1/webhooks/dlr/line route that Orbit registers as part of connect — nothing for you to wire. Full envelope samples are on the channel page.

5. Verify the loop end to end

From a LINE device, message your Official Account — confirm a message.received event lands on your webhook within seconds.
Reply through POST /messages/line using the sender’s U… id from that event — confirm the message arrives in the chat.
Confirm the message.delivered event arrives and that the message record in the dashboard moved through queued → delivered.

If inbound never arrives, check the LINE Developers Console webhook section: Use webhook must be enabled and the URL must be exactly https://api.orbit.devotel.io/api/v1/webhooks/inbound/line. LINE also enforces that webhook URL validation responds on the same domain — if you rotate credentials, re-paste them in Orbit rather than re-pointing the URL.

6. Rotation and retirement

Rotating the access token from the LINE Developers Console does not break history — Orbit keys conversation history by channel id, not by token, and re-pasting the new token value under Channels → LINE preserves everything. Disconnecting the channel in the dashboard removes the credential row; inbound webhook traffic for that channel id then resolves to no tenant and is rejected, so retire it only after the Official Account has stopped receiving traffic.

7. Error reference

A failed send returns a JSON error envelope whose error.code is one of the values below.

Code	HTTP	Cause	Fix
`VALIDATION_ERROR`	422	`to` or `body` missing, `body` exceeds 5000 characters, or a `flex` message’s `flex_contents` is not valid JSON.	Correct the request body and retry.
`INVALID_RECIPIENT`	422	`to` is empty or is not a usable LINE recipient id.	Reply to a user (`U…`), group (`C…`), or room (`R…`) id taken from an inbound event.
`MESSAGE_SEND_FAILED`	502	LINE’s Messaging API rejected the push, or a token rotated after connect.	For a token rotation, re-paste the current token under Channels → LINE. Otherwise check the failure reason on the status webhook and retry.
`RATE_LIMITED`	429	More than 80 sends/minute for the tenant.	Honour the `Retry-After` header; stage bulk sends through the campaigns API.

LINE_INVALID_TOKEN (401) is returned only at connect time, for an expired or invalid channel access token; it is never raised on the send path. The connect response that carries it — and the branch to write for it — is shown in §2.

Compliance scope

LINE does not impose platform-side template or quiet-hours gates on plain text, and Orbit does not either — any consent, opt-out, or timing policy you promise your LINE audience is enforced from your own tenant configuration (quiet hours, frequency caps, suppression lists), not by this channel’s connect path. Keep those controls enabled in production and follow them in your journey logic; this guide only wires the transport.

Where to go next

LINE channel page — message types, capability detail, pricing notes.
Asia channels onboarding — LINE beside KakaoTalk, Viber, and WeChat.
API recipes cookbook — the four-channel complement pack: the send → poll → webhook loop task by task, with curl and per-language SDK snippets, including the LINE send under the Asia-channels task.
Inbound webhook debugging — tools for the receiver side on any channel.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

LINE onboarding: Messaging API channel to working two-way chat

LINE Onboarding: Messaging API Channel to Working Two-Way Chat

1. Prerequisites — the Messaging API channel

2. Connect the channel to Orbit

3. Send — POST /api/v1/messages/line

The full send with metadata — six languages

Sticker and flex messages

The response envelope

4. Inbound — tenant resolution from `destination`

5. Verify the loop end to end

6. Rotation and retirement

7. Error reference

Compliance scope

Where to go next

​LINE Onboarding: Messaging API Channel to Working Two-Way Chat

​1. Prerequisites — the Messaging API channel

​2. Connect the channel to Orbit

​3. Send — POST /api/v1/messages/line

​The full send with metadata — six languages

​Sticker and flex messages

​The response envelope

​4. Inbound — tenant resolution from destination

​5. Verify the loop end to end

​6. Rotation and retirement

​7. Error reference

​Compliance scope

​Where to go next

LINE Onboarding: Messaging API Channel to Working Two-Way Chat

1. Prerequisites — the Messaging API channel

2. Connect the channel to Orbit

3. Send — POST /api/v1/messages/line

The full send with metadata — six languages

Sticker and flex messages

The response envelope

4. Inbound — tenant resolution from `destination`

5. Verify the loop end to end

6. Rotation and retirement

7. Error reference

Compliance scope

Where to go next