搜尋聯絡人

開發者可以透過 API 查詢帳號下的聯絡人列表，支援依聯絡人的 email、phone_number、name、identifier 進行搜尋。

請求方式

GET

呼叫位址

https://livedesk-api.engagelab.com/api/v2/accounts/contacts

呼叫驗證

詳情請參見 API 概述的驗證方式說明。

請求

請求範例

curl -X GET https://livedesk-api.engagelab.com/api/v2/accounts/contacts?q=support@engagelab.com\ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \

              
              curl -X GET https://livedesk-api.engagelab.com/api/v2/accounts/contacts?q=support@engagelab.com\
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \

此代碼塊在浮窗中顯示

請求標頭

字段	類型	描述
Authorization	string	使用 `Authorization: Basic base64(API Key:API Secret)` 進行身分驗證。請前往 API 金鑰頁面取得 API Key 和 API Secret，並將兩者以冒號連接後進行 Base64 編碼。
Content-Type	application/json	資料類型，一般文字訊息使用 application/json。

Query 參數

字段	類型	必填	描述
q	string	否	查詢參數，聯絡人屬性欄位包括 email/phone_number/name/identifier
page	integer	否	頁碼，預設為 1，每頁 15 筆
labels	string / string[]	否	依標籤篩選，支援多個標籤（任一匹配）
include_contact_inboxes	boolean	否	是否回傳 contact_inboxes，預設為 `true`
sort	string	否	排序欄位，可選值：`email`、`name`、`phone_number`、`last_activity_at`、`created_at`、`company`、`city`、`country`
direction	string	否	排序方向，`asc` 或 `desc`

回應範例

{ "meta": { "count": 1, "current_page": 1 }, "payload": [ { "additional_attributes": { "source_id": "email:ed5c8362-425c-4589-8adb-61a033d8c5fb.support@engagelab.com" }, "availability_status": "offline", "email": "support@engagelab.com", "id": 64464046, "name": "support", "phone_number": null, "blocked": false, "identifier": null, "thumbnail": "", "custom_attributes": {}, "last_activity_at": 1778572024, "created_at": 1778570103, "contact_inboxes": [ { "source_id": "support@engagelab.com", "inbox": { "id": 985, "channel_id": 107, "name": "邮箱", "channel_type": "Channel::Email", "provider": null } } ] } ] }

              
              {
    "meta": {
        "count": 1,
        "current_page": 1
    },
    "payload": [
        {
            "additional_attributes": {
                "source_id": "email:ed5c8362-425c-4589-8adb-61a033d8c5fb.support@engagelab.com"
            },
            "availability_status": "offline",
            "email": "support@engagelab.com",
            "id": 64464046,
            "name": "support",
            "phone_number": null,
            "blocked": false,
            "identifier": null,
            "thumbnail": "",
            "custom_attributes": {},
            "last_activity_at": 1778572024,
            "created_at": 1778570103,
            "contact_inboxes": [
                {
                    "source_id": "support@engagelab.com",
                    "inbox": {
                        "id": 985,
                        "channel_id": 107,
                        "name": "邮箱",
                        "channel_type": "Channel::Email",
                        "provider": null
                    }
                }
            ]
        }
    ]
}

此代碼塊在浮窗中顯示

回應參數

字段	類型	必填	描述
count	Int	否	查詢結果數量。
current_page	Int	否	查詢結果頁碼。
payload	Object	否	屬性結構。
additional_attributes	Object	否	附加屬性。
availability_status	String	否	線上狀態，預設為 offline。
email	String	否	電子郵件地址。
id	String	否	聯絡人 ID。
name	String	否	名稱。
phone_number	String	否	手機號碼。
blocked	String	否	是否鎖定，預設為 false。
identifier	String	否	聯絡人外部唯一識別，對應介面顯示的 UserID。
thumbnail	String	否	頭像 URL。
custom_attributes	String	否	聯絡人屬性。
created_at	String	否	建立時間戳。
last_activity_at	String	否	最新更新時間戳。
contact_inboxes	Array	否	關聯的渠道資訊，僅在 `include_contact_inboxes=true` 時回傳
source_id	String	否	渠道 ID。
inbox	Object	否	通道資訊。
id	String	否	通道 ID。
name	String	否	通道名稱。
channel_type	String	否	通道類型。
provider	String	否	廠商，例如通道為 whatsapp，對應值為 whatsapp_cloud/engagelab_whatsapp/twilio。不區分廠商的通道為空值 null。