LINE Messaging API 怎麼傳圖片？一次看懂圖片推播與 Flex 換行設定

使用 LINE Messaging API 傳送圖片時，不能直接把本機圖檔、byte[] 或 multipart/form-data 丟進訊息傳送端點；正確方式是先把圖片放在 LINE 伺服器可公開存取的 HTTPS 網址，再將圖片原圖與預覽圖網址寫入 JSON。Flex Message 也是以 JSON 描述版型，若要處理文字換行，除了加入 \n，還必須依需求設定 wrap、maxLines 與元件尺寸。以下將從頻道建立、Webhook、圖片處理到 Flex Message Action，完整說明實作方式。

LINE Messaging API 是什麼

「LINE Messaging API 是什麼」是開發 LINE 聊天機器人前最重要的問題。正式名稱為 LINE Messaging API，它是 LINE 提供給開發者的互動式訊息服務，可讓系統接收使用者傳來的事件，並自動回覆或主動推送訊息。

Messaging API 常見用途包括客服機器人、訂單通知、預約提醒、會員查詢、群組服務與系統告警。可使用的訊息格式包含文字、貼圖、圖片、影片、音訊、位置資訊、Imagemap、Template Message 與 Flex Message。

Messaging API 與已於 2025 年 3 月 31 日終止服務的 LINE Notify 不同。Messaging API 必須結合 LINE 官方帳號，並透過 Channel Access Token 呼叫 API，但能控制訊息對象、互動行為與顯示版型，因此更適合正式服務。

Messaging API 的三種傳送方式

回覆訊息是收到 Webhook 事件後，使用事件內的 replyToken 回覆。回覆必須在有效期限內盡快完成，不應儲存 replyToken 供日後使用。

推播訊息是使用 User ID、Group ID 或 Room ID 主動發送。群發與窄播則適合符合資格的官方帳號進行大量訊息傳送，但仍受方案、權限及訊息用量限制。

訊息格式比較表

訊息格式	適用情境	內容來源	是否支援互動
Text Message	一般通知、客服回覆	JSON 文字	可搭配文字連結
Sticker Message	簡短情緒回應	LINE 提供的貼圖 ID	否
Image Message	商品圖、圖表、照片	公開 HTTPS 圖片網址	否
Template Message	按鈕、確認、輪播	固定樣板 JSON	是
Flex Message	訂單卡片、商品選單、會員資訊	自訂 Flex JSON	是
Location Message	門市或活動位置	經緯度與地址	可開啟地圖
PDF 或一般檔案	提供文件下載	以 HTTPS 網址搭配 URI Action	是

Messaging API 並非所有檔案都能當成訊息附件直接傳送。若要提供 PDF，常見作法是在文字或 Flex Message 按鈕中放入 HTTPS 下載網址，而不是將 PDF 的二進位內容直接交給訊息 API。

LINE Messaging API 教學：建立官方帳號與頻道

完整的 LINE Messaging API 教學應從 LINE 官方帳號開始。開發者需先登入 LINE Developers 與 LINE Official Account Manager，建立 Provider 與官方帳號，再為官方帳號啟用 Messaging API。實際選單名稱可能因後台改版而調整，應以 LINE Developers 官方文件顯示為準。

建立步驟

1. 登入 LINE Developers Console。
2. 建立或選擇 Provider。
3. 建立 LINE 官方帳號，並啟用 Messaging API。
4. 在 Messaging API 頻道中取得 Channel ID 與 Channel Secret。
5. 簽發 Channel Access Token，正式環境建議使用可管理有效期的權杖機制。
6. 在官方帳號回應設定中啟用 Webhook。
7. 填入可由外部連線的 HTTPS Webhook URL。
8. 使用後台的 Verify 功能確認伺服器能正常回應。

Channel Access Token 等同 API 憑證，不可放入前端 JavaScript、公開 Git 儲存庫或 App 安裝包。正式環境應存放於環境變數、Secret Manager 或其他機密管理服務。

LINE Messaging API 教學：Webhook 接收與驗證

LINE Messaging API 教學不能只說明如何發送訊息，也必須正確處理 Webhook。使用者加入好友、傳送文字、圖片或在群組中互動時，LINE 會將事件以 HTTP POST 傳到指定網址。

伺服器收到事件後，應使用 Channel Secret 驗證 x-line-signature。其計算方式是以原始 request body 進行 HMAC-SHA256，再轉為 Base64。若先把 JSON 解析後重新序列化，內容可能改變，導致簽章驗證失敗。

驗證成功後，再依 events[].type 與 events[].message.type 判斷事件。例如 text 代表文字，image 代表圖片，video 代表影片。系統也應記錄 Webhook Event ID，避免重送事件造成重複處理。

使用者與群組識別碼

一對一聊天通常可從事件的 source.userId 取得 User ID；群組事件則可能包含 source.groupId，多人聊天室可能包含 Room ID。這些識別碼屬於敏感資料，應限制存取、加密保存，並依個資保護需求設定保留期限。

官方帳號被加入群組後，還必須確認後台允許加入群組或多人聊天室。能否取得成員資料，也會受到事件類型、權限與 API 規則限制。

LINE Messaging API 傳送圖片的正確作法

LINE Messaging API 傳送圖片與傳統檔案上傳 API 不同。發送 Image Message 時，請求本文只提供圖片網址，不是圖片二進位資料。

圖片通常需要準備兩個可公開存取的 HTTPS 網址：

1. originalContentUrl：使用者開啟圖片時看到的原圖。
2. previewImageUrl：聊天室訊息中顯示的預覽圖。

兩個網址都必須讓 LINE 伺服器直接存取，不能要求登入、Cookie 或額外的 Authorization Header。網址也不應指向只在公司內網、localhost 或 VPN 中才能開啟的資源。

圖片推播 JSON 範例

json

{

“to”: “Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”,

“messages”: [

{

“type”: “image”,

“originalContentUrl”: “https://cdn.example.com/images/order-1001.jpg”,

“previewImageUrl”: “https://cdn.example.com/images/order-1001-preview.jpg”

}

]

}

請將內容 POST 到：

https://api.line.me/v2/bot/message/push

HTTP Header 應包含：

Authorization: Bearer {CHANNEL_ACCESS_TOKEN}
Content-Type: application/json

圖片格式、容量、尺寸與 URL 長度限制可能隨平台調整，上線前應以 LINE Messaging API 官方文件的最新規格為準。

圖片網址的實務要求

建議將圖片放在具有效 TLS 憑證的物件儲存空間或 CDN，例如自行管理的雲端儲存服務。伺服器回應應使用正確的 Content-Type，例如 image/jpeg 或 image/png，並避免多次重新導向。

如果使用具有到期時間的簽署網址，有效期限必須足以讓 LINE 抓取圖片及讓使用者稍後查看。期限過短可能導致預覽正常，但使用者點開原圖時已經失效。

不建議將包含個資、醫療資訊或機密訂單資料的圖片放在永久公開網址。若業務涉及敏感資料，可改用需要身分驗證的會員頁面，並在 Flex Message 中提供登入連結。

接收使用者圖片並儲存

當使用者把圖片傳給機器人時，Webhook 不會直接附上完整圖片，而會提供圖片訊息 ID。伺服器需使用該 ID 呼叫訊息內容端點：

GET https://api-data.line.me/v2/bot/message/{messageId}/content

請求必須帶入 Channel Access Token。成功後取得的是二進位串流，可儲存到伺服器或物件儲存空間。

圖片處理流程

1. 接收並驗證 Webhook。
2. 確認訊息類型為 image。
3. 取得 message.id。
4. 呼叫訊息內容端點下載二進位資料。
5. 檢查檔案類型、容量與內容安全性。
6. 產生不會衝突的檔名。
7. 儲存至受控空間。
8. 依個資政策設定刪除期限。

舊式教學常使用 Imgur API 重新上傳圖片，但這不是必要步驟，也未必適合商業或敏感資料。較安全的方式是使用企業自行控制的儲存空間，並設定存取權限、生命週期與操作紀錄。

Flex Message 是什麼

Flex Message 是什麼？Flex Message 是以 JSON 定義的 LINE 客製化訊息格式，其排版概念接近 CSS Flexbox。開發者可以組合圖片、標題、價格、說明、分隔線與按鈕，製作比純文字更清楚的卡片式內容。

Flex Message 最外層訊息包含 type、altText 與 contents。contents 可使用 Bubble 或 Carousel。Bubble 適合單張卡片，Carousel 則可橫向排列多張 Bubble。

altText 是必要的替代文字，會用於不支援 Flex Message 的環境、通知預覽或部分裝置顯示，因此不能只填入「Flex Message」，應寫成能表達內容的摘要。

Flex Message 教學：建立第一張卡片

以下 Flex Message 教學示範一張簡單的訂單通知卡片。實際資料應由後端安全地替換，不要直接拼接未經處理的使用者輸入。

json

{

“type”: “flex”,

“altText”: “訂單編號 A1001 已成立”,

“contents”: {

“type”: “bubble”,

“header”: {

“type”: “box”,

“layout”: “vertical”,

“contents”: [

{

“type”: “text”,

“text”: “訂單已成立”,

“weight”: “bold”,

“size”: “xl”

}

]

},

“body”: {

“type”: “box”,

“layout”: “vertical”,

“spacing”: “md”,

“contents”: [

{

“type”: “text”,

“text”: “訂單編號：A1001”

},

{

“type”: “text”,

“text”: “預計出貨：2026/09/08”,

“wrap”: true

}

]

},

“footer”: {

“type”: “box”,

“layout”: “vertical”,

“contents”: [

{

“type”: “button”,

“action”: {

“type”: “uri”,

“label”: “查看訂單”,

“uri”: “https://example.com/orders/A1001”

}

}

]

}

}

}

正式傳送前，可先使用 LINE 官方提供的 Flex Message Simulator 檢查 JSON、版型與裝置預覽。模擬器能協助找出欄位錯誤，但不代表實際 API 一定成功；仍需確認 Token、訊息配額、網址與傳送對象。

Flex Message 換行設定

Flex Message 換行最常見的方式是在 text 欄位中加入換行字元 \n，並將 wrap 設為 true。

json

{

“type”: “text”,

“text”: “付款方式：信用卡\n配送方式：宅配\n預計到貨：2026/09/10”,

“wrap”: true

}

如果 JSON 是由程式碼字串建立，通常需要處理跳脫。例如程式中的 \\n 經過序列化後，才可能成為 JSON 內容中的 \n。建議使用 JSON 序列化函式建立物件，不要手動串接整段 JSON。

wrap: true 代表文字寬度不足時可自動折行；\n 則是指定位置強制換行，兩者用途不同。若設定 maxLines，超過行數的文字可能被截斷，因此訂單備註、地址等長文字要先在不同螢幕尺寸測試。

Flex Message Action 互動設定

Flex Message Action 是 Flex Message 的互動核心。Action 可放在按鈕、圖片或特定元件上，使用者點擊後可開啟網址、傳送文字或回傳資料給 Webhook。

常見 Action 比較表

Action 類型	點擊結果	適合用途
URI Action	開啟 HTTPS 網頁或支援的 URI	商品頁、付款頁、PDF 下載
Message Action	以使用者身分送出指定文字	選單指令、快速查詢
Postback Action	將資料傳回 Webhook	訂單操作、狀態切換
Datetime Picker Action	選擇日期或時間後回傳	預約、到貨日期
Camera Action	開啟相機	上傳收據或現場照片
Camera Roll Action	開啟相簿	選擇既有圖片
Location Action	開啟位置分享介面	門市配送、定位服務

Postback Action 適合程式判斷，不必在聊天室中顯示指令文字。例如可傳送 action=confirm&orderId=A1001。伺服器收到後仍須再次驗證使用者身分、訂單歸屬及目前狀態，不能因為資料來自按鈕就直接信任。

URI Action 若連到付款、會員或訂單頁面，建議結合 LINE Login 或 LIFF 完成身分確認。不要把永久有效的登入 Token、個資或管理權限直接放在網址參數中。

Flex Message 中文內容設計原則

Flex Message 中文排版需要特別注意中文字寬、標點與不同裝置的字級差異。同一段內容在 Android、iOS 與桌面版 LINE 中，可能呈現不同的換行位置。

卡片標題應直接說明狀態，例如「付款成功」或「訂單已出貨」。重要資訊應放在前方，不要只靠顏色表達狀態。金額、日期、訂單編號與按鈕名稱也應使用一致格式。

Flex Message 不適合塞入完整文章。若資訊過多，應在卡片顯示摘要，再透過 URI Action 導向網頁。如此不但提升可讀性，也更容易更新內容與進行權限控管。

上線前的安全與除錯檢查

Webhook 必須驗證簽章，Channel Access Token 必須妥善保存。所有圖片與連結均應使用有效 HTTPS，並確認 LINE 伺服器能在不登入的情況下存取必要資源。

上線檢查清單

1. Webhook URL 可從外部使用 HTTPS 連線。
2. x-line-signature 使用原始 request body 驗證。
3. Channel Access Token 未出現在前端或公開儲存庫。
4. 圖片網址回傳正確 HTTP 狀態與 Content-Type。
5. Flex JSON 已通過模擬器與 API 實際測試。
6. altText 能清楚表達訊息內容。
7. Postback 操作在後端重新驗證身分與狀態。
8. User ID、圖片及對話紀錄具有保存與刪除規則。
9. 系統能處理 Webhook 重送，避免重複建立訂單。
10. 已監控 API 回應狀態碼，但不在紀錄中輸出完整 Token。

遇到 400 Bad Request 時，通常應檢查 JSON 結構、必要欄位、網址格式與 Flex 元件層級。收到 401 Unauthorized 時，應確認 Token 是否正確、過期或屬於另一個頻道。若 API 回應成功但圖片無法顯示，則應檢查 HTTPS 憑證、重新導向、存取限制與網址有效期限。

結論

LINE Messaging API 的圖片傳送流程是「先提供可存取的 HTTPS 圖片，再把網址交給 LINE」，而不是直接上傳 multipart 檔案。接收使用者圖片時，則要利用訊息 ID 呼叫內容端點，取得二進位資料後自行保存與管理。

Flex Message 能將文字、圖片與 Flex Message Action 整合成互動卡片。實作時應正確處理 Flex Message 換行、altText、JSON 跳脫、Webhook 簽章及網址安全。正式規格、容量限制與支援欄位可能更新，部署前應再次核對 LINE Developers 官方文件。

常見問題

1. LINE Messaging API 可以直接傳送本機圖片嗎？

不可以。Image Message 必須提供 LINE 伺服器能存取的 HTTPS 原圖與預覽圖網址，不能填入本機路徑或直接傳送 byte[]。

2. 可以使用 multipart/form-data 傳送圖片訊息嗎？

訊息傳送端點主要接收 JSON，不是透過 multipart/form-data 上傳圖片。應先將圖檔放到網站、物件儲存空間或 CDN，再把網址寫入 JSON。

3. 圖片網址可以要求登入嗎？

通常不可以，因為 LINE 伺服器無法代替使用者完成網站登入，也不會自動附帶自訂 Authorization Header。圖片資源必須能被 LINE 直接取得。

4. Messaging API 可以直接傳送 PDF 嗎？

一般做法不是把 PDF 當成圖片或二進位附件發送，而是在文字訊息或 Flex Message 中加入 URI Action，讓使用者開啟 HTTPS 文件下載頁。

5. Flex Message 為什麼一定要有 altText？

altText 用於通知預覽及不支援 Flex Message 的顯示環境。內容應簡短說明卡片重點，不能留空。

6. Flex Message 文字如何強制換行？

在 text 中加入 \n，並視需求設定 wrap: true。若使用程式建立 JSON，要注意字串跳脫與序列化結果。

7. wrap 與換行字元有什麼不同？

wrap: true 是空間不足時自動折行；\n 是在指定位置強制換行。兩者可同時使用。

8. 如何取得使用者傳給機器人的圖片？

先從 Webhook 取得圖片訊息 ID，再呼叫 /v2/bot/message/{messageId}/content 內容端點下載二進位資料。

9. Postback Action 可以直接執行訂單操作嗎？

後端可以依 Postback 資料執行操作，但必須再次驗證使用者、訂單歸屬、權限與狀態，不能完全信任按鈕傳回的參數。

10. 為什麼 Flex Message 模擬器正常，API 傳送卻失敗？

常見原因包括 Channel Access Token 錯誤、傳送對象無效、JSON 外層訊息格式不完整、圖片網址無法公開存取，或使用了目前 API 不支援的屬性。應依 API 回傳的狀態碼與錯誤內容逐項檢查。