联系人

添加联系人

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

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

支持的渠道

调用前准备

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

参数从哪里取得

account_id: 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。获取账号

请求

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
  }
}'

请求参数

请求头

X-Api-Key

string必填

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

Content-Type

string必填

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

路径参数

account_id

string必填

用于该 contacts 路由的标识符。

请求体

phone_number

string

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

minLength: 1

username

string

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

minLength: 1

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。

如何理解结果

按本接口的响应字段和 HTTP 状态判断结果，再通过相关操作选择下一步。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "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"
    }
  }
}

响应体

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 设置的个人名称。

username

string

WhatsApp 联系人的用户名（provider=whatsapp），与个人名称 push_name 独立。列表和详情仅在已获取到非空用户名时返回；缺失表示当前未知，不代表对方未设置，也不应据此清空已保存的用户名。

minLength: 1

business_name

string

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

redacted_phone

string

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

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

403

禁止访问

请求已识别，但不允许执行该操作。

404

未找到

未找到请求的资源；请结合 error.code 和当前操作核对。

409

冲突

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

500

服务端错误

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

501

渠道未实现

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

502

上游网关错误

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

失败后怎么处理

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

结合当前操作读取 HTTP 状态、error.code 和 error.numeric_code。数字码按字符串处理。保留 request_id 排障；它不是幂等键或任务标识。

invalid_request · 10000 · 400

检查 JSON 请求体和必填字段。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON；message 随实际原因变化 · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

工作区覆盖目标为空或格式无效。移除覆盖请求头，改用目标工作区所属的 API Key。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON；message 随实际原因变化 · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

provider_invalid_request · 30001 · 400

检查渠道专属字段及其格式。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON；message 随实际原因变化 · 400 · 30001

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

invalid_api_key · 11001 · 401

检查 API Key 是否正确且已启用。

处理与重试: 保留 request_id 与结构化错误码，先排查当前操作，再决定下一步。

示意 JSON；message 随实际原因变化 · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

请添加 X-Api-Key 请求头。

处理与重试: 保留 request_id 与结构化错误码，先排查当前操作，再决定下一步。

示例 · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

请求尝试使用此 API Key 无权使用的工作区覆盖。移除覆盖请求头，改用目标工作区所属的 API Key。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 保留 request_id 与结构化错误码，先排查当前操作，再决定下一步。

示意 JSON；message 随实际原因变化 · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

覆盖指定的工作区不存在或不可用。核对工作区归属，移除覆盖请求头并使用目标工作区 API Key；重复请求不会增加访问权限。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示意 JSON；message 随实际原因变化 · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_binding_not_found · 30006 · 409

账号尚无有效的渠道连接绑定，请检查账号状态。

处理与重试: 查询授权与运行态，再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出；依赖连接的业务操作前确认 running。

示意 JSON；message 随实际原因变化 · 409 · 30006

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

egress_configuration_pending · 20032 · 409

当前无法确认或读取平台默认网络配置；这不表示账号已退出登录。

触发条件: 本操作使用平台分配的网络容量或账号固定的默认网络配置。

处理与重试: 保留 request_id，再次写入前核对账号或创建结果。等待容量或配置恢复，或联系支持；不要自动反复创建账号、更换网络或重启账号。

示意 JSON；message 随实际原因变化 · 409 · 20032

{
  "request_id": "req_example",
  "error": {
    "code": "egress_configuration_pending",
    "numeric_code": "20032",
    "message": "Account network configuration is pending verification"
  }
}

provider_not_ready · 30009 · 409

连接尚未就绪，请检查授权及 runtime_status 后再决定是否重试。

处理与重试: 查询授权与运行态，再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出；依赖连接的业务操作前确认 running。

示意 JSON；message 随实际原因变化 · 409 · 30009

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

provider_not_ready · 30014 · 409

此账号所需的渠道实例缺失。这是运行实例可用性问题，不证明授权已过期。

处理与重试: 查询授权与运行态，再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出；依赖连接的业务操作前确认 running。

适用渠道: WhatsApp

示意 JSON；message 随实际原因变化 · 409 · 30014

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}

provider_not_ready · 30015 · 409

渠道运行进程已停止。启动前确认这是否为预期状态；运行态停止本身不等于已登出。

处理与重试: 查询授权与运行态，再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出；依赖连接的业务操作前确认 running。

适用渠道: WhatsApp

示意 JSON；message 随实际原因变化 · 409 · 30015

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}

create_contact_failed · 20020 · 500

核对 account_id，并使用账号所属工作区的 X-Api-Key。此工作区下未找到的账号不能用当前 Key 访问。

触发条件: 适用于账号不存在的情况；保留原 HTTP 状态和操作 code，通过 numeric_code 细分账号缺失。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示意 JSON；message 随实际原因变化 · 500 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

create_contact_failed · 30010 · 500

渠道未能完成本次操作。message 可能在 “Provider operation failed:” 后附带原始原因；原因文本可变，不是稳定的程序接口。

触发条件: 适用于渠道未提供更具体失败分类的情况，保留当前操作的错误。

处理与重试: 再次创建前先列出或查询已有资源，确认上次创建是否已生效。修正根本原因并保留 request_id，不要自动创建重复资源。

适用渠道: WhatsApp

示意 JSON；message 随实际原因变化 · 500 · 30010

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}

create_contact_failed · 30017 · 500

上游渠道明确因请求过密拒绝请求。此数字分类保留当前操作既有的 HTTP 状态与 code。

处理与重试: 暂停请求，按有次数上限的策略延后重试。此处不承诺固定等待时间或 Retry-After 处理；重试写操作前确认上次结果。

适用渠道: WhatsApp

示意 JSON；message 随实际原因变化 · 500 · 30017

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30017",
    "message": "Provider rate limit exceeded"
  }
}

create_contact_failed · 30018 · 500

账号的渠道 App State 基线失步。这是账号同步状态问题，不是通用请求格式错误。

处理与重试: 等待渠道恢复账号的 App State 基线，再检查当前状态后重试。不要仅凭此分类推断凭据失效或重新发起授权。

适用渠道: WhatsApp

示意 JSON；message 随实际原因变化 · 500 · 30018

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30018",
    "message": "Provider app state is out of sync"
  }
}

create_contact_failed · 30021 · 500

本次请求时账号未连接到消息平台。WhatsApp 添加联系人可返回 500 / create_contact_failed / 30021。这不证明账号已退出登录，也不保证当前运行态仍为 disconnected；先查询当前状态，再选择恢复动作。

处理与重试: 暂停依赖连接的业务操作。先调用 POST /v1/accounts/{account_id}/runtime/refresh，按最新状态恢复，确认 runtime_status=running 后再请求业务接口。重发前确认上一次写入结果。

适用渠道: WhatsApp

示意 JSON；message 随实际原因变化 · 500 · 30021

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30021",
    "message": "Account is not connected to the messaging platform"
  }
}

create_contact_failed · 35003 · 500

添加联系人：资源创建失败或无法确认创建结果。

处理与重试: 再次创建前先列出或查询已有资源，确认上次创建是否已生效。修正根本原因并保留 request_id，不要自动创建重复资源。

示意 JSON；message 随实际原因变化 · 500 · 35003

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "35003",
    "message": "Failed to create contact"
  }
}

create_contact_failed · 35009 · 500

WhatsApp 本次未将目标号码识别为有效联系人；不能据此断言号码未注册或永久不可用。

处理与重试: 与用户核对国家区号、号码和 WhatsApp 注册状态，并查看 error.message。确认原因后再请求，不要对同一号码持续自动重试。

适用渠道: WhatsApp

示例 · 500 · 35009

{
  "request_id": "req_example_contact_not_active",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "35009",
    "message": "Target phone number was not recognized as an active WhatsApp contact"
  }
}

unsupported_by_provider · 30003 · 501

渠道不支持此操作，请选择能力表中支持的操作。

处理与重试: 选择文档列为支持的渠道与动作。重复请求不会增加能力或开通内测权限。

示例 · 501 · 30003

{
  "request_id": "req_xxx",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}

provider_adapter_not_found · 30004 · 502

渠道服务暂不可用，请检查状态或稍后再试；重试写操作前先确认上次结果。

处理与重试: 再次创建前先列出或查询已有资源，确认上次创建是否已生效。修正根本原因并保留 request_id，不要自动创建重复资源。

示意 JSON；message 随实际原因变化 · 502 · 30004

{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}

provider_unavailable · 30002 · 502

渠道服务暂不可用，请检查状态或稍后再试；重试写操作前先确认上次结果。

处理与重试: 再次创建前先列出或查询已有资源，确认上次创建是否已生效。修正根本原因并保留 request_id，不要自动创建重复资源。

示例 · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}

provider_unavailable · 30010 · 502

渠道未能完成本次操作。message 可能在 “Provider operation failed:” 后附带原始原因；原因文本可变，不是稳定的程序接口。

处理与重试: 再次创建前先列出或查询已有资源，确认上次创建是否已生效。修正根本原因并保留 request_id，不要自动创建重复资源。

适用渠道: WhatsApp

示例 · 502 · 30010

{
  "request_id": "req_example_operation_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}

provider_unavailable · 30021 · 502

适用渠道: WhatsApp

示例 · 502 · 30021

{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}