按联系人标识查询对话 | LiveDesk API Contact 简体中文

外部系统可通过联系人的业务标识、邮箱或完整电话号码，查询该项目下关联的普通对话编号、创建时间和当前状态。返回的对话编号可直接用于现有的对话详情、消息等 V2 接口。

请求方式

GET

调用地址

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

调用验证

本接口使用 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 一致。接口不会补充默认国家区号，也不支持按号码尾号匹配。
GET 参数必须进行正确的 URL 编码，尤其电话号码中的 + 应编码为 %2B。

查询范围与排序

联系人和对话均只在凭证所属项目内查询。接口返回该联系人在项目内所有收件箱关联的普通对话（conversation_category=chat），不包含工单对话，也不按当前坐席、分配人员或收件箱筛选。

所有状态的普通对话都会返回：open、resolved、pending、snoozed、closed。本接口不提供状态筛选；即使传入 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 对话详情、消息等接口。
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`	历史数据导致同一项目中匹配到多个联系人。接口不会任意选择其中一个联系人；请改用唯一的 `identifier` 查询。
`422`	`type` 缺失或不支持；`value` 缺失、为空白、非字符串或格式不正确；或分页参数不是正整数。

使用说明

该接口仅新增查询能力，不会修改联系人或对话数据。
接口不兼容以模糊匹配方式查找联系人；请确保外部系统保存的 identifier、邮箱或电话号码与 LiveDesk 中的联系人属性一致。
若需要处理查询结果中的对话，请使用响应 payload[].id 作为对外对话编号继续调用相应 V2 接口。