查询联系人

开发者可以通过 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[]	否	按标签过滤，支持多个标签（any 匹配）
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	否	是否锁定，默认falese。
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。