🐍 如何不使用 SDK 直接呼叫 LINE Messaging API (以 Python 為例)
本文件旨在說明如何不依賴任何官方 SDK,直接透過 HTTP 請求與 LINE Messaging API 進行互動。這對於理解 API 底層運作、在不支援 SDK 的環境中開發,或是進行簡單的腳本整合非常有幫助。
我們將以 Python 的 requests 函式庫為例,示範如何傳送一個最基本的文字訊息。
🛠️ 1. 前置準備
在開始之前,請確保你已經擁有:
- 一個 LINE Developers 帳號:如果沒有,請至 LINE Developers Console 註冊。
- 一個 Messaging API 的 Channel:在 Console 中建立一個提供者 (Provider),然後在該提供者下建立一個 Messaging API 的 Channel。
- Channel Access Token (長期):這是呼叫 API 所需的憑證。你可以在 Channel 的 “Messaging API” 分頁中找到並發行它。
- 你的 User ID:為了測試 Push Message,你需要一個目標對象的 User ID。
如何取得 User ID最簡單的方式是將你的機器人帳號加為好友,然後傳送任何訊息給它。接著,你需要設定 Webhook 來接收這個訊息事件,從中取得你的 User ID。
💡 2. 核心概念:Push Message
「主動傳送訊息」(Push Message) 是指由機器人主動發送訊息給用戶,不需要用戶先有互動。
- HTTP 方法:
POST - API 端點 (Endpoint):
https://api.line.me/v2/bot/message/push - HTTP Headers:
Content-Type:application/jsonAuthorization:Bearer {你的 Channel Access Token}
- Request Body (Payload):一個 JSON 物件,用來描述訊息的接收者 (
to) 和內容 (messages)。
🚀 3. 步驟詳解:傳送 Push Message
3.1 準備必要資訊
YOUR_CHANNEL_ACCESS_TOKEN: 從你的 LINE Developers Console 複製。YOUR_USER_ID: 你想要傳送訊息對象的 User ID。
3.2 撰寫 Python 程式碼
Body (Payload) 的結構:
{ "to": "YOUR_USER_ID", "messages": [ { "type": "text", "text": "Hello, world!" } ]}💻 4. 完整 Python 範例 (Push Message)
import requestsimport json
ACCESS_TOKEN = 'YOUR_CHANNEL_ACCESS_TOKEN'USER_ID = 'YOUR_USER_ID'
PUSH_API_URL = 'https://api.line.me/v2/bot/message/push'
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {ACCESS_TOKEN}'}
payload = { 'to': USER_ID, 'messages': [{'type': 'text','text': '這是一則來自 Python 的 Push Message!'}]}
try: response = requests.post(PUSH_API_URL, headers=headers, data=json.dumps(payload)) response.raise_for_status() print('Push Message 傳送成功!')except requests.exceptions.RequestException as e: print('Push Message 傳送失敗:', e)▶️ 5. 如何執行
- 安裝
requests:pip install requests - 儲存檔案:將範例程式碼儲存為
.py檔案。 - 替換變數:填入你的
ACCESS_TOKEN和USER_ID。 - 執行腳本:
python <your_script_name>.py
↩️ 6. 如何回覆訊息 (Reply Message)
「回覆訊息」(Reply Message) 是針對用戶傳來的特定訊息進行回應。這與可以隨時傳送的 Push Message 不同。
核心差異:
- API 端點:
https://api.line.me/v2/bot/message/reply - 認證方式:使用
replyToken而不是to。 replyToken:當用戶傳送訊息到你的聊天機器人時,LINE 會透過 Webhook 事件傳送一個replyToken給你。這個 Token 是 一次性 且有 時效性 的,只能用來回覆該則訊息一次。
Body (Payload) 的結構:
{ "replyToken": "從 Webhook 取得的 Reply Token", "messages": [ { "type": "text", "text": "感謝您的訊息!" } ]}範例程式碼 (概念)
你無法直接執行此腳本,因為 replyToken 必須從真實的 Webhook 事件中動態取得。這段程式碼展示了在一個 Web 框架 (如 Flask 或 FastAPI) 中處理回覆的邏輯。
# (這是一個概念性範例,假設在一個 Web 伺服器環境中)
# 假設你從 LINE Webhook 收到了這樣的 JSON bodywebhook_event = { "events": [ { "type": "message", "replyToken": "nHuyWiB7yP5Zw52FIkcQobQuGDXCTA", # 範例 Token "message": { "type": "text", "id": "14320195349999", "text": "你好" } } ]}
# 取得 replyTokenreply_token = webhook_event['events'][0]['replyToken']
# --- 準備回覆請求 ---REPLY_API_URL = 'https://api.line.me/v2/bot/message/reply'ACCESS_TOKEN = 'YOUR_CHANNEL_ACCESS_TOKEN'
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {ACCESS_TOKEN}'}
payload = { 'replyToken': reply_token, 'messages': [{'type': 'text', 'text': '這是一則 Reply Message!'}]}
# --- 發送回覆 ---try: response = requests.post(REPLY_API_URL, headers=headers, data=json.dumps(payload)) response.raise_for_status() print('Reply Message 傳送成功!')except requests.exceptions.RequestException as e: print('Reply Message 傳送失敗:', e)💬 7. 如何引用訊息 (Quote Message)
引用訊息是 Reply Message 的一項附加功能,可以讓用戶清楚地看到你的回覆是針對哪一則訊息。
要使用此功能,你需要在回覆的 messages 物件中,加上 quoteToken 欄位。
quoteToken:與replyToken一樣,quoteToken也來自於 Webhook 事件中的message物件。它代表了用戶傳來的那則訊息的引用標識。
Body (Payload) 結構 (帶有引用):
{ "replyToken": "從 Webhook 取得的 Reply Token", "messages": [ { "type": "text", "text": "這是對你那句話的回覆。", "quoteToken": "從 Webhook 取得的 Quote Token" } ]}範例程式碼 (概念)
# (接續上一個 Webhook 範例)
# 從 Webhook 事件中同時取得 replyToken 和 quoteTokenwebhook_event = webhook_event['events'][0]reply_token = webhook_event['replyToken']quote_token = webhook_event['message']['quoteToken'] # quoteToken 在 message 物件內
# --- 準備帶有引用的回覆請求 ---payload = { 'replyToken': reply_token, 'messages': [ { 'type': 'text', 'text': '我正在引用你的訊息來回覆!', 'quoteToken': quote_token } ]}
# --- 發送回覆 ---try: response = requests.post(REPLY_API_URL, headers=headers, data=json.dumps(payload)) response.raise_for_status() print('帶引用的 Reply Message 傳送成功!')except requests.exceptions.RequestException as e: print('Reply Message 傳送失敗:', e)🎁 8. 進階:傳送不同類型的訊息
不論是 Push 還是 Reply Message,你都可以傳送文字以外的訊息類型,只需修改 messages 陣列的內容即可。
範例:傳送貼圖
{ "type": "sticker", "packageId": "11537", "stickerId": "52002734"}提示:你可以在 貼圖列表文件 中找到可用的
packageId和stickerId。
📡 9. 關於接收 Webhook 事件
本文件中的 Reply Message 和 Quote Message 都強烈依賴 Webhook 來取得必要的 replyToken 和 quoteToken。
簡單來說,你需要:
- 準備一個公開的 HTTPS 伺服器端點 (URL)。
- 在 LINE Developers Console 中設定你的 Webhook URL。
- 當有事件發生時,LINE 平台會對你的 URL 發送一個
POST請求。 - 你的伺服器需要解析這個請求的 JSON 內容,並 驗證簽名 (Signature) 以確保請求來自 LINE。簽名驗證需要使用你的 Channel Secret。
手動處理 Webhook(特別是簽名驗證)比傳送訊息要複雜得多,這也是官方 SDK 主要的價值所在。
⚠️ 10. 重要注意事項:傳送圖片訊息中的 URL 有中文字時
當你嘗試透過 LINE Messaging API 傳送圖片訊息的 URL時,請務必對該 URL 進行 URL 編碼 (URL Encoding)。如果未經編碼且URL裡有中文子時,LINE 平台可能無法正確解析該 URL,導致訊息無法成功傳送或顯示異常。
這在傳送可點擊的連結或指定資源位置時尤其重要。大多數程式語言都內建了 URL 編碼的工具函式。
圖片訊息中的 URL 編碼
當你在傳送圖片訊息 (Image Message) 時,其 originalContentUrl 和 previewImageUrl 也必須是經過編碼的有效 URL。
Body (Payload) 的結構:
{ "type": "image", "originalContentUrl": "編碼後的圖片 URL", "previewImageUrl": "編碼後的預覽圖片 URL"}範例程式碼 (概念)
from urllib.parse import quote
# 原始的圖片 URLraw_image_url = "https://example.com/images/my cat photo.jpg"raw_preview_url = "https://example.com/images/preview/my cat photo.jpg"
# 對 URL 進行編碼encoded_image_url = quote(raw_image_url, safe='/:')encoded_preview_url = quote(raw_preview_url, safe='/:')
# --- 準備圖片訊息的 payload ---payload = { 'to': USER_ID, 'messages': [ { "type": "image", "originalContentUrl": encoded_image_url, "previewImageUrl": encoded_preview_url } ]}
# --- 發送請求 ---# response = requests.post(PUSH_API_URL, headers=headers, data=json.dumps(payload))重點:
quote函式會將特殊字元 (如空格、?,=,&) 轉換為%開頭的格式。safe='/:,'參數可以避免對 URL 的協定 (https://) 和路徑分隔符 (/) 等本身合法的字元進行編碼。- 若不進行編碼,像 URL 中的空格或特殊查詢參數,可能會被 LINE 的伺服器誤判,導致 URL 無法存取、圖片載入失敗,最終使您的 API 請求失敗。
📝 11. 總結
直接呼叫 API 的優點:
- 輕量:不需要安裝整個 SDK,只依賴基本的 HTTP 客戶端。
- 彈性:可以在任何支援 HTTP 請求的語言或環境中使用。
- 透明:能清楚了解 API 的底層運作方式。
直接呼叫 API 的缺點:
- 繁瑣:需要手動組合 JSON、設定 Headers。
- 錯誤處理:需要自行處理 HTTP 錯誤、API 回應的錯誤碼等。
- Webhook 複雜:手動實作 Webhook 的簽名驗證相對複雜且容易出錯。
對於僅需傳送簡單通知的腳本,直接呼叫 API 是一個非常好的選擇。但若要開發功能完整的聊天機器人,使用官方 SDK 通常會更有效率且穩健。