联系人

获取联系人详情

实时返回联系人详情。普通联系人不存在返回 404 contact_not_found；目标会话不存在时返回 422 contact_not_found、numeric_code=35000、message=Conversation not found。

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/contacts/info

调用前准备

在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。

参数从哪里取得

account_id: 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。获取账号
contact_id: 渠道侧联系人标识，按不透明字符串传递。whatsapp 和 whatsapp-protocol 统一使用 LID（xxx@lid）。whatsapp-protocol 联系人资料字段缺失时仍可能返回成功，请以实际返回字段为准。

WhatsApp Protocol: 联系人详情需要已有 LID（xxx@lid）。只有入站事件的 data.sender.id 或 data.conversation.id 已以 @lid 结尾时才能直接复用。Protocol 不提供联系人列表查询，此接口也不能从手机号推算 LID；没有 LID 时无法进行此项查询。成功响应可能缺少资料字段。

请求参数

请求头

X-Api-Key

string必填

工作区 API Key，工作区由该请求头解析得到。

路径参数

account_id

string必填

用于该 contacts 路由的标识符。

查询参数

contact_id

string必填

渠道侧联系人标识，按不透明字符串传递。whatsapp 和 whatsapp-protocol 统一使用 LID（xxx@lid）。whatsapp-protocol 联系人资料字段缺失时仍可能返回成功，请以实际返回字段为准。

请求体

该接口无需 JSON 请求体。

如何理解结果

仅使用实际返回的资料字段。联系人标识按不透明字符串处理，字段缺失不等于联系人不存在。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "user_example",
    "conversation_id": "peer_example",
    "display_name": "Alice",
    "avatar_url": "",
    "provider_user_id": "user_example",
    "extra": {
      "phone": "8600000000000"
    }
  }
}

响应体

id

string

联系人标识。

conversation_id

string

该联系人的会话标识，用于发送消息或定位聊天。

display_name

string

联系人显示名，缺失时为空字符串。

avatar_url

string

联系人头像 URL，缺失时为空字符串。

provider_user_id

string

联系人在渠道侧的用户标识。

is_blocked

boolean

该联系人是否已被当前账号屏蔽。

extra

object

渠道专属的额外字段，例如 phone。

phone

string

WhatsApp phone JID 中解析出的纯手机号。

first_name

string

当前账号通讯录中保存的联系人简称或名字部分。

full_name

string

当前账号通讯录中保存的完整联系人名称。

push_name

string

联系人自行在 WhatsApp 设置的个人名称。

business_name

string

WhatsApp Business 账号的商业或认证名称。

redacted_phone

string

Provider 仅返回部分号码时的遮蔽手机号。

响应

200

200 OK

请求成功，响应体示例如上。

400

请求错误

请求体、路径或参数不合法。

401

未授权

X-Api-Key 请求头缺失或无效。

404

未找到

未找到请求的渠道资源。

409

冲突

当前操作与已有的渠道账号或资源冲突。

422

无法处理的实体

请求格式有效，但无法解析目标渠道会话。

500

服务端错误

服务端遇到了未预期的错误。

501

渠道未实现

所选渠道尚未实现该操作。

502

上游网关错误

渠道适配器或上游渠道未能完成该操作。

失败后怎么处理

检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。错误码参考

invalid_request · 10000 · 400: 检查必填字段、格式和渠道条件，修正请求后再调用。
invalid_api_key · 11001 · 401: 检查 X-Api-Key 是否正确、工作区是否有效。