← API 参考
联系人POST

添加联系人

向渠道账号添加联系人。phone_number 与 username 至少提供一个；whatsapp_options 仅适用于 WhatsApp，不支持的渠道返回 501 unsupported_by_provider。

https://api.unifyport.ai/v1/accounts/{account_id}/contacts/add

请求头

X-Api-Key
string必填

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

Content-Type
string必填

发送 JSON 请求体时使用 application/json。

路径参数

account_id
string必填

用于该 contacts 路由的标识符。

请求体

phone_number
string

包含国家或地区代码的纯数字电话号码，不含加号、空格或分隔符；与 username 至少提供一个。

username
string

渠道用户名；与 phone_number 至少提供一个，格式以目标渠道为准。

whatsapp_options
object

可选的 WhatsApp 联系人设置；first_name、full_name、sync_to_device_contacts 只能嵌套在 whatsapp_options 内传入，其他渠道应省略该对象。

first_name
string

可选的 WhatsApp 联系人名字。

full_name
string

可选的 WhatsApp 联系人全名。

sync_to_device_contacts
boolean

是否同时保存到当前 WhatsApp 账号关联设备的系统通讯录，默认为 false。

响应体

id
string

联系人标识。

conversation_id
string

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

display_name
string

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

avatar_url
string

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

provider_user_id
string

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

is_blocked
boolean

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

extra
object

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

响应

200
200 OK

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

400
请求错误

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

401
未授权

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

409
冲突

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

500
服务端错误

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

501
渠道未实现

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

502
上游网关错误

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

请求

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/contacts/add \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "8600000000000",
  "username": "alice_user",
  "whatsapp_options": {
    "first_name": "Alice",
    "full_name": "Alice Example",
    "sync_to_device_contacts": false
  }
}'

响应

{
  "data": {
    "id": "8600000000000@s.whatsapp.net",
    "conversation_id": "123456789012345@lid",
    "display_name": "Alice Example",
    "avatar_url": "",
    "provider_user_id": "8600000000000@s.whatsapp.net",
    "extra": { "phone": "8600000000000" }
  }
}