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

# 發送 LINE 訊息

> 透過公開 API 或 MCP 傳送文字給已綁定的聯絡人，並查詢發送結果。

在「設定 → API」建立具有 `line:send` 的 Public API 金鑰。查詢發送結果需另勾選 `line:read`；既有金鑰不會自動取得這兩個權限。

組織須已設定 LINE 官方帳號、啟用 LINE 模組。收件人必須是同組織聯絡人，而且唯一綁定的個人 LINE 帳號仍追蹤官方帳號。未綁定、已取消追蹤或同時綁定多個有效帳號時，API 回傳 `409 resource_state_conflict`，原因在 `error.details.reason`。不支援群組發送。

## 發送文字

此操作會發出真實 LINE 訊息。請使用已確認的收件人與內容，並為每次獨立的發送意圖建立一個非機密的 `Idempotency-Key`。

```curl theme={null}
curl --request POST 'https://api.brightalk.ai/line-messages' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: line-example-update-1" \
  --data '{"contact_id":"123e4567-e89b-42d3-a456-426614174000","message":"Hello, your requested update is ready."}'
```

文字會原樣傳送，不展開自動化的範本變數。上限為 5000 個 UTF-16 編碼單位；部分表情符號計為兩個單位。API 不接受 LINE 使用者 ID、頻道憑證、組織 ID 或任意收件人覆寫。

`201` 代表建立發送紀錄，請繼續檢查回應的 `status`：

| status | 意義 | 後續動作 |
| - | - | - |
| `sent` | LINE 已接受請求，不保證送達或已讀 | 保留 `id`，不再發送 |
| `failed` | 發送遭拒或未通過發送前檢查 | 依 `error_code` 處理原因後，以新金鑰再次嘗試 |
| `pending` | 正在處理，尚無確定結果 | 使用相同金鑰讀回紀錄或查詢狀態 |
| `unknown` | 結果不明，可能已送出 | 查明結果，勿換新金鑰重發 |

## 查詢與重送

```curl theme={null}
curl --request GET 'https://api.brightalk.ai/line-messages/123e4567-e89b-42d3-a456-426614174000' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16"
```

請將路徑中的 ID 換成發送回應的 `id`。此查詢僅涵蓋公開 API／MCP 建立的發送紀錄，不是收件匣歷史 API。訊息會同步寫入 CRM 的 LINE 收件匣。

相同 `Idempotency-Key` 和內容重送時，只會讀回同一筆紀錄的目前狀態，並回傳 `Idempotency-Replayed: true`。相同金鑰搭配不同內容會得到 `409 idempotency_conflict`。這些防重送紀錄不會到期；即使刪除收件匣訊息或聯絡人，也不會再次發送。一分鐘內尚未開始發送者顯示 `failed` 與 `dispatch_not_started`，之後也無法再發送；已開始發送卻沒有記錄結果者顯示 `unknown`。LINE HTTP 429（速率限制或每月配額）是明確拒絕，回傳 `failed` 與 `provider_rejected`；等待限制解除或處理配額後，可用新金鑰再次嘗試。逾時或服務商 5xx 仍為 `unknown`。

## MCP

發送工具是 `brightalk_send_line_message`：

```json theme={null}
{
  "body": {
    "contact_id": "123e4567-e89b-42d3-a456-426614174000",
    "message": "您好，您詢問的訂單已完成處理。"
  },
  "idempotency_key": "contact-order-update-1"
}
```

查詢工具是 `brightalk_get_line_message`，輸入 `{ "message_id": "發送回應的 id" }`。MCP 查詢模式會隱藏發送工具；需啟用操作模式並使用具有 `line:send` 的金鑰。

## 衝突原因

`409 resource_state_conflict` 的原因位於 `error.details.reason`。這些衝突發生時尚未建立發送紀錄，修正原因後可沿用相同金鑰重試。

| reason | 意義與處理方式 |
| - | - |
| `line_not_linked` | 尚未綁定個人 LINE 帳號；請綁定聯絡人 |
| `line_not_following` | 已綁定帳號未追蹤官方帳號；請收件人追蹤 |
| `line_multiple_accounts` | 同時綁定多個仍追蹤的個人帳號；請保留唯一綁定 |
| `line_recipient_invalid` | 綁定的 LINE 使用者 ID 無效；請修正綁定 |
| `line_channel_missing` | 組織尚未設定 LINE 頻道；請完成設定 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.