依聯絡人識別碼查詢對話 | LiveDesk API Contact 繁體中文

外部系統可透過聯絡人的業務識別碼、電子郵件或完整電話號碼，查詢該專案下關聯的一般對話編號、建立時間與目前狀態。回傳的對話編號可直接用於現有的對話詳情、訊息等 V2 API。

請求方式

GET

呼叫網址

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup

驗證方式

本 API 使用 HTTP Basic 驗證。請在請求標頭中傳入 Authorization，使用者名稱為 API Key，密碼為 API Secret；憑證所屬專案即為本次查詢範圍，無需在路徑中傳入專案 ID。詳情請參閱 API 概述。

若請求中傳入 account_id，其值必須與憑證所屬專案一致；不一致時會回傳 401。

請求

請求範例

curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup?type=identifier&value=Customer_123&page=1&page_size=20' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)'

              
              curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup?type=identifier&value=Customer_123&page=1&page_size=20' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'

此代碼塊在浮窗中顯示

依電話號碼查詢時，+ 必須進行 URL 編碼：

GET /api/v2/accounts/conversations/lookup?type=phone&value=%2B15551234567

              
              GET /api/v2/accounts/conversations/lookup?type=phone&value=%2B15551234567

此代碼塊在浮窗中顯示

請求標頭參數

欄位	類型	必填	說明
`Authorization`	string	是	使用 `Authorization: Basic base64(API Key:API Secret)` 進行身分驗證。請將 API Key 與 API Secret 以冒號連接後進行 Base64 編碼。

Query 參數

欄位	類型	必填	說明
type	string	是	查詢屬性類型，僅允許 `identifier`、`email`、`phone`。
value	string	是	非空字串，依 `type` 對應的聯絡人屬性進行精確比對。
page	integer	否	正整數，預設為 `1`。
page_size	integer	否	正整數，預設為 `20`；大於 `50` 時會以 `50` 查詢。
account_id	integer	否	專案 ID。通常無需傳入；傳入時必須與憑證所屬專案一致，否則回傳 `401`。

比對規則

identifier：區分大小寫，保留原始值，不進行子字串或萬用字元比對。
email：先移除前後空白並驗證電子郵件格式，再忽略大小寫進行精確比對。
phone：先移除前後空白；必須使用含 + 與國碼的完整號碼，且格式需與聯絡人的 phone_number 一致。API 不會補上預設國碼，也不支援依電話尾碼比對。
GET 參數必須正確進行 URL 編碼，尤其電話號碼中的 + 應編碼為 %2B。

查詢範圍與排序

聯絡人與對話均僅在憑證所屬專案內查詢。API 會回傳該聯絡人在專案內所有收件匣關聯的一般對話（conversation_category=chat），不包含工單對話，也不依目前客服人員、指派人員或收件匣篩選。

所有狀態的一般對話都會回傳：open、resolved、pending、snoozed、closed。本 API 不提供狀態篩選；即使傳入 status，也不會縮小查詢範圍。

結果依對話建立時間倒序排列；建立時間相同時，依內部對話主鍵倒序排列。資料未變更時，分頁順序穩定。頁碼分頁不保證在並行建立或刪除期間提供一致的快照。

回應

成功回應

HTTP 200：

{ "meta": { "count": 2, "current_page": 1, "page_size": 20, "total_pages": 1 }, "payload": [ { "id": 202609000000002, "created_at": 1788739200, "status": "closed", "inbox_id": 12, "contact_id": 901 }, { "id": 202609000000001, "created_at": 1788652800, "status": "open", "inbox_id": 10, "contact_id": 901 } ] }

              
              {
  "meta": {
    "count": 2,
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1
  },
  "payload": [
    {
      "id": 202609000000002,
      "created_at": 1788739200,
      "status": "closed",
      "inbox_id": 12,
      "contact_id": 901
    },
    {
      "id": 202609000000001,
      "created_at": 1788652800,
      "status": "open",
      "inbox_id": 10,
      "contact_id": 901
    }
  ]
}

此代碼塊在浮窗中顯示

回應參數

欄位	類型	說明
meta	object	分頁中繼資料。
count	integer	符合條件的一般對話總數，包含所有狀態，不受分頁影響。
current_page	integer	目前頁碼。
page_size	integer	實際每頁筆數；請求值大於 `50` 時為 `50`。
total_pages	integer	總頁數；無結果時為 `0`。
payload	array	目前頁面的對話清單。
id	integer	對外對話編號，即 `conversations.display_id`；可直接用於現有 V2 對話詳情、訊息等 API。
created_at	integer	對話建立時間，Unix 秒時間戳記。
status	string	目前對話狀態，可能為 `open`、`resolved`、`pending`、`snoozed` 或 `closed`。
inbox_id	integer	所屬收件匣編號。
contact_id	integer	符合條件的聯絡人編號。

聯絡人不存在、聯絡人沒有一般對話，或請求頁碼超出總頁數時，均會回傳 HTTP 200。在前兩種情況及頁碼超出總頁數時，payload 為空陣列；meta.count 會始終保留實際總數。

回應僅包含上述欄位，不會回傳訊息、附件或聯絡人的個人資訊。

錯誤回應

錯誤回應統一為以下結構，錯誤說明不會回顯查詢值：

{ "error": "錯誤說明" }

              
              {
  "error": "錯誤說明"
}

此代碼塊在浮窗中顯示

HTTP 狀態碼	情境
`401`	憑證無效、已停用或已失效，或請求中的 `account_id` 與憑證所屬專案不一致。
`409`	歷史資料導致同一專案中符合條件的聯絡人有多筆。API 不會任意選擇其中一位聯絡人；請改用唯一的 `identifier` 查詢。
`422`	`type` 缺失或不支援；`value` 缺失、僅包含空白、非字串或格式不正確；或分頁參數不是正整數。

使用說明

此 API 僅新增查詢功能，不會修改聯絡人或對話資料。
API 不支援以模糊比對方式尋找聯絡人；請確保外部系統儲存的 identifier、電子郵件或電話號碼與 LiveDesk 中的聯絡人屬性一致。
若需處理查詢結果中的對話，請使用回應中的 payload[].id 作為對外對話編號，繼續呼叫相應的 V2 API。