> ## 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.

# 聯絡人

> 瞭解 REST API 中的聯絡人、API 資源識別碼與外部識別。

<Note>
  **私人測試版。** 新組織預設已啟用。組織管理員仍須在 Brightalk 設定中建立具權限範圍的 API 金鑰，請求才能通過驗證。可用範圍與限制以本文件和 OpenAPI 契約為準。
</Note>

聯絡人是通話、批次與 Automation 執行共同使用，且侷限於組織範圍內的單一且具權威性的聯絡人紀錄。資源 ID 為不透明字串；請保存傳回的 `id`，不要從格式推論意義。

## 聯絡人參照

執行請求可接受既有的 `contact_id`，或以 `recipient` 提供內嵌收話人資料。內嵌收話人資料包含 `external_id`、`name` 與 `phone_number`，也可包含其他支援的聯絡人欄位。Brightalk 會將資料解析為單一且具權威性的聯絡人紀錄，並在執行資源中傳回該 `contact_id`。

`external_id` 是呼叫端在 `source` 命名空間中管理的外部識別碼。請使用您系統內穩定的值，不要使用顯示名稱或會變更的電話標籤。

## 採用與衝突規則

建立或解析內嵌收話人資料時，Brightalk 會以不可分割的方式套用以下規則：

1. 相符的外部識別會解析至既有且具權威性的聯絡人紀錄。
2. 相符的正規化電話只有在既有聯絡人沒有外部識別時，才能採用請求指定的外部識別。
3. 若該電話已屬於另一個非空的外部識別，請求會傳回 `409 contact_identity_conflict`，且不覆寫任一識別。
4. 其餘情況會以支援的欄位建立新聯絡人。

`POST /contacts` 建立新聯絡人時傳回 `201`，遇到既有或採用的聯絡人時傳回 `200`。未知欄位會遭拒絕。

## 電話格式與組織隔離

`phone_number` 必須採用嚴格 E.164 格式：以 `+` 開頭、國碼不得為零，且總長度為 8–15 位數字。語法正確不保證組織已啟用該目的地；執行可能安全地以 `unsupported_destination` 失敗。

識別查詢、電話衝突與資源存取都依組織隔離。請求無法跨組織合併聯絡人，也無法透過請求欄位選擇組織。