LINE API 串接教學：Messaging API、Login 與 LIFF

Provider "My Shop"
├── Messaging API channel   （與 LINE 官方帳號連動）
├── LINE Login channel      （網站登入＋LIFF app）
└── LINE MINI App channel   （視需要）

# .env
LINE_CHANNEL_ACCESS_TOKEN=...
LINE_CHANNEL_SECRET=...
LINE_LOGIN_CHANNEL_ID=...
LINE_LOGIN_CHANNEL_SECRET=...

// line-api.ts：用 fetch 寫的精簡 Messaging API 用戶端（Node.js 22 以上）
const API = "https://api.line.me/v2/bot"
const token = process.env.LINE_CHANNEL_ACCESS_TOKEN
if (!token) throw new Error("Set LINE_CHANNEL_ACCESS_TOKEN")

export type LineMessage = { type: string; [key: string]: unknown }

export class LineApiError extends Error {
  constructor(public status: number, public requestId: string | null, public body: string) {
    super(`LINE API ${status}: ${body}`)
  }
}

async function post(path: string, body: unknown, headers: Record<string, string> = {}) {
  const res = await fetch(`${API}${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, ...headers },
    body: JSON.stringify(body),
  })
  if (!res.ok) throw new LineApiError(res.status, res.headers.get("x-line-request-id"), await res.text())
  return res.json() as Promise<{ sentMessages?: { id: string; quoteToken?: string }[] }>
}

// 回覆：需要 Webhook 事件的 replyToken，最多 5 則，不計入訊息則數
export function reply(replyToken: string, messages: LineMessage[]) {
  return post("/message/reply", { replyToken, messages })
}

// 推播：傳給 1 位使用者、1 個群組或聊天室；重試同一次推播時沿用同一個 retryKey（UUID）
export function push(to: string, messages: LineMessage[], retryKey: string) {
  return post("/message/push", { to, messages }, { "X-Line-Retry-Key": retryKey })
}

// Multicast：每次請求最多 500 個 user ID
export function multicast(to: string[], messages: LineMessage[]) {
  if (to.length > 500) throw new Error("multicast accepts at most 500 user IDs")
  return post("/message/multicast", { to, messages })
}

import { randomUUID } from "node:crypto"
import { push, type LineMessage } from "./line-api.js"

const userId = "U0123456789abcdef0123456789abcdef"
const welcome: LineMessage[] = [
  {
    type: "text",
    text: "您的訂單 #1042 已出貨。",
    quickReply: {
      items: [
        { type: "action", action: { type: "uri", label: "查詢物流", uri: "https://example.com/track/1042" } },
        { type: "action", action: { type: "message", label: "聯絡客服", text: "我想詢問訂單 #1042" } },
      ],
    },
  },
]
const retryKey = randomUUID()
const result = await push(userId, welcome, retryKey)
console.log(result.sentMessages?.map((m) => m.id))

{ "type": "text", "text": "您好！請問需要什麼協助？" }

{
  "type": "image",
  "originalContentUrl": "https://example.com/photo.jpg",
  "previewImageUrl": "https://example.com/photo-preview.jpg"
}

{
  "type": "flex",
  "altText": "週末限定：飲品 8 折",
  "contents": {
    "type": "bubble",
    "hero": {
      "type": "image",
      "url": "https://example.com/promo.jpg",
      "size": "full",
      "aspectRatio": "20:13",
      "aspectMode": "cover"
    },
    "body": {
      "type": "box",
      "layout": "vertical",
      "contents": [
        { "type": "text", "text": "週末限定優惠", "weight": "bold", "size": "xl" },
        { "type": "text", "text": "全品項飲料 8 折，到週日為止", "wrap": true }
      ]
    },
    "footer": {
      "type": "box",
      "layout": "vertical",
      "contents": [
        {
          "type": "button",
          "style": "primary",
          "action": { "type": "uri", "label": "查看菜單", "uri": "https://example.com/menu" }
        }
      ]
    }
  }
}

// login.ts：用 Express 5 實作「使用 LINE 登入」（授權碼流程＋PKCE）
import express from "express"
import { createHash, randomBytes } from "node:crypto"

const CHANNEL_ID = process.env.LINE_LOGIN_CHANNEL_ID!
const CHANNEL_SECRET = process.env.LINE_LOGIN_CHANNEL_SECRET!
const REDIRECT_URI = "https://example.com/auth/line/callback" // 必須與 Console 設定的 Callback URL 相同

const app = express()
// 示範用的暫存；正式環境請改用 session store 或資料庫
const pending = new Map<string, { nonce: string; codeVerifier: string }>()

function readCookie(header: string | undefined, name: string) {
  return header?.split(/;\s*/).find((c) => c.startsWith(`${name}=`))?.slice(name.length + 1)
}

app.get("/auth/line", (_req, res) => {
  const state = randomBytes(16).toString("hex")
  const nonce = randomBytes(16).toString("hex")
  const codeVerifier = randomBytes(32).toString("base64url") // 43 個字元
  const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url")
  pending.set(state, { nonce, codeVerifier })
  res.cookie("line_state", state, { httpOnly: true, secure: true, sameSite: "lax", maxAge: 10 * 60 * 1000 })

  const params = new URLSearchParams({
    response_type: "code",
    client_id: CHANNEL_ID,
    redirect_uri: REDIRECT_URI,
    state,
    scope: "profile openid",
    nonce,
    code_challenge: codeChallenge,
    code_challenge_method: "S256",
  })
  // URLSearchParams 會把空格編成 "+"，LINE 文件範例使用 %20
  res.redirect(`https://access.line.me/oauth2/v2.1/authorize?${params.toString().replaceAll("+", "%20")}`)
})

app.get("/auth/line/callback", async (req, res) => {
  const { code, state, error } = req.query
  const saved = typeof state === "string" ? pending.get(state) : undefined
  if (typeof state === "string") pending.delete(state)
  if (error || typeof code !== "string" || !saved || state !== readCookie(req.headers.cookie, "line_state")) {
    res.status(400).send("Login cancelled or invalid state") // 使用者拒絕授權時會帶 error=ACCESS_DENIED
    return
  }

  // 1. 用授權碼換取 Token
  const tokenRes = await fetch("https://api.line.me/oauth2/v2.1/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code,
      redirect_uri: REDIRECT_URI,
      client_id: CHANNEL_ID,
      client_secret: CHANNEL_SECRET,
      code_verifier: saved.codeVerifier,
    }),
  })
  if (!tokenRes.ok) {
    res.status(502).send("Token exchange failed")
    return
  }
  const { access_token, id_token } = (await tokenRes.json()) as { access_token: string; id_token: string }

  // 2. 交給 LINE 驗證 ID Token（簽章、Channel ID、效期、nonce）
  const verifyRes = await fetch("https://api.line.me/oauth2/v2.1/verify", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ id_token, client_id: CHANNEL_ID, nonce: saved.nonce }),
  })
  if (!verifyRes.ok) {
    res.status(401).send("Invalid ID token")
    return
  }
  const claims = (await verifyRes.json()) as { sub: string; name?: string; picture?: string }

  // 3. 選用：用 Access Token 取得最新個人檔案
  const profile = await fetch("https://api.line.me/v2/profile", {
    headers: { Authorization: `Bearer ${access_token}` },
  }).then((r) => r.json() as Promise<{ userId: string; displayName: string; pictureUrl?: string }>)

  // claims.sub 是此 Provider 下的使用者 ID，在這裡建立登入 session
  console.log(claims.sub, profile.displayName)
  res.redirect("/")
})

app.listen(3000)

// LIFF app（瀏覽器端）：取得 ID Token，交給伺服器驗證
import liff from "@line/liff"

await liff.init({ liffId: "1234567890-AbcdEfgh" })
if (!liff.isLoggedIn()) {
  liff.login() // 外部瀏覽器才需要；在 LIFF 瀏覽器中使用者已登入
} else {
  const idToken = liff.getIDToken() // 需要 openid scope
  await fetch("/api/me", { method: "POST", headers: { Authorization: `Bearer ${idToken}` } })
}

// webhook.ts：不用 SDK 接收事件（Express 5）
import express from "express"
import { createHmac, timingSafeEqual } from "node:crypto"
import { reply } from "./line-api.js"

const CHANNEL_SECRET = process.env.LINE_CHANNEL_SECRET!
const app = express()

function isValidSignature(rawBody: Buffer, signature: string | undefined) {
  if (!signature) return false
  const expected = createHmac("sha256", CHANNEL_SECRET).update(rawBody).digest()
  const received = Buffer.from(signature, "base64")
  return received.length === expected.length && timingSafeEqual(received, expected)
}

type LineEvent = {
  type: string
  webhookEventId: string
  deliveryContext: { isRedelivery: boolean }
  replyToken?: string
  source?: { type: string; userId?: string; groupId?: string; roomId?: string }
  message?: { id: string; type: string; text?: string }
  postback?: { data: string }
}

// express.raw 保留 LINE 簽章時的原始位元組；這個路由不要用 express.json()
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body
  if (!Buffer.isBuffer(rawBody) || !isValidSignature(rawBody, req.get("x-line-signature"))) {
    res.sendStatus(401)
    return
  }
  const { events } = JSON.parse(rawBody.toString("utf8")) as { events: LineEvent[] }
  res.sendStatus(200) // 盡快回應，events 為 []（連線檢查）時也一樣
  for (const event of events) handleEvent(event).catch((err) => console.error(err))
})

const seen = new Set<string>() // 正式環境請用設有 TTL 的 Redis 或資料庫

async function handleEvent(event: LineEvent) {
  if (seen.has(event.webhookEventId)) return // 重新傳送或重複的事件
  seen.add(event.webhookEventId)

  switch (event.type) {
    case "message":
      if (event.replyToken && event.message?.type === "text") {
        await reply(event.replyToken, [{ type: "text", text: `您說：${event.message.text}` }])
      }
      break
    case "follow":
      if (event.replyToken) await reply(event.replyToken, [{ type: "text", text: "感謝您加入好友！" }])
      break
    case "postback": {
      const data = new URLSearchParams(event.postback?.data) // 例如 "action=book&slot=10:00"
      console.log("postback", data.get("action"), data.get("slot"))
      break
    }
    case "unfollow":
      // 沒有 replyToken：使用者已封鎖，停止傳訊給 event.source?.userId
      break
  }
}

app.listen(Number(process.env.PORT ?? 3000))

# app.py：同樣的 Webhook 改用 Python（line-bot-sdk v3，Python 3.10 以上）
import os
from flask import Flask, request, abort
from linebot.v3 import WebhookHandler
from linebot.v3.exceptions import InvalidSignatureError
from linebot.v3.messaging import (
    ApiClient, Configuration, MessagingApi, ReplyMessageRequest, TextMessage,
)
from linebot.v3.webhooks import FollowEvent, MessageEvent, TextMessageContent

app = Flask(__name__)
configuration = Configuration(access_token=os.environ["LINE_CHANNEL_ACCESS_TOKEN"])
handler = WebhookHandler(os.environ["LINE_CHANNEL_SECRET"])


@app.post("/webhook")
def webhook():
    signature = request.headers.get("X-Line-Signature", "")
    body = request.get_data(as_text=True)  # 解析 JSON 之前的原始 body
    try:
        handler.handle(body, signature)
    except InvalidSignatureError:
        abort(401)
    return "OK"


@handler.add(MessageEvent, message=TextMessageContent)
def on_text(event):
    with ApiClient(configuration) as api_client:
        MessagingApi(api_client).reply_message(
            ReplyMessageRequest(
                reply_token=event.reply_token,
                messages=[TextMessage(text=f"您說：{event.message.text}")],
            )
        )


@handler.add(FollowEvent)
def on_follow(event):
    with ApiClient(configuration) as api_client:
        MessagingApi(api_client).reply_message(
            ReplyMessageRequest(
                reply_token=event.reply_token,
                messages=[TextMessage(text="感謝您加入好友！")],
            )
        )

import { randomUUID } from "node:crypto"
import { LineApiError, push, type LineMessage } from "./line-api.js"

export async function pushWithRetry(to: string, messages: LineMessage[], attempts = 3) {
  const retryKey = randomUUID() // 每次重試都用同一個 key
  for (let attempt = 1; ; attempt++) {
    try {
      return await push(to, messages, retryKey)
    } catch (err) {
      if (err instanceof LineApiError && err.status === 409) return // 先前的請求已被受理
      const retryable = !(err instanceof LineApiError) || err.status === 429 || err.status >= 500
      if (!retryable || attempt >= attempts) throw err
      await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 1000))
    }
  }
}