API 参考

消息

发送名片（vCard）消息

发送名片消息。message.contacts 必须是非空数组，且每张名片的 name 必须非空；phones[].number、emails[].address、organization、title 可选。目前仅 WhatsApp 支持；内容不合法返回 400 invalid_request，非 WhatsApp provider 返回 400 unsupported_message_type。

POSThttps://api.unifyport.ai/v1/messages

支持的渠道

WhatsApp

调用前准备

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

完成所选授权流程并检查 runtime_status。授权与连接是两个状态，仅有 HTTP 成功不能证明账号已经就绪。

参数从哪里取得
account_id
从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号
to.id · to.type
回复消息时，将 message.received 中的 data.conversation.id 和 data.conversation.type 分别复制到 to.id、to.type。发送给新收件方时遵循对应渠道的标识规则。 统一消息发送能力

请求参数

请求头

X-Api-Key
string必填

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

Content-Type
string必填

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

请求体

provider_data
object

渠道专属发送选项，仅在对应渠道和消息类型支持时生效。WhatsApp audio/video 的 seconds 使用非负整数；仅在 video 时使用 0 到 4294967295，waveform 仅适用于 audio。支持引用回复时请使用顶层 reply_to。sticker 的 provider_data 只能省略或为空对象；非对象返回 400 invalid_request，非空对象返回 400 provider_invalid_request。

seconds
integer

WhatsApp audio 或 video 消息的可选时长，单位为秒，使用非负整数；仅在 video 时，取值范围为 0 到 4294967295。

minimum: 0

waveform
string

WhatsApp audio 消息的可选音频波形数据。非空值必须使用标准 Base64 编码，且解码后必须是可解析的 JSON 波形数据；空字符串按未提供处理，其他格式错误返回 HTTP 400 provider_invalid_request。

account_id
string必填

发送该消息的渠道账号。

minLength: 1

to
object必填

收件方目标，包含 id 与 type。

id
string必填

收件方在渠道侧的标识。

minLength: 1

type
string必填

标准会话类型：user、group 或 channel。WhatsApp 社群公告群继续使用 group。

enum: user, group, channel

message
object必填

标准化消息载荷：文本使用 message.text，媒体使用 message.url。

type
string必填

消息类型：text、image、video、audio、document、file、contact、link_preview、poll 或 sticker。

enum: text, image, video, audio, document, file, contact, link_preview, poll, sticker

text
string

text 和 link_preview 必填的非空正文。link_preview 要求包含非空白字符；WhatsApp 还要求正文包含 link_preview.url 的原文。

minLength: 1

caption
string

image、video、document 或 file 消息的可选说明文字。

url
string

非空绝对 HTTP(S) 媒体 URL；媒体消息需在 url / file_url / file_key 中至少提供一个。

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_url
string

非空备用绝对 HTTP(S) 媒体 URL；媒体消息需在三个来源字段中至少提供一个。

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_key
string

非空渠道或存储文件引用；媒体消息需在三个来源字段中至少提供一个。

contacts[]
object[]

message.type=contact 时必填的非空结构化名片数组。

minItems: 1

name
string

每张名片必填的非空联系人显示名。

minLength: 1

phones[]
object[]

名片中包含的电话号码列表。

number
string

电话号码；每个 phone 条目都必须提供。

type
string

可选的电话类型，例如 CELL 或 WORK。

emails[]
object[]

名片中包含的电子邮箱列表。

address
string

电子邮箱地址；每个 email 条目都必须提供。

format: email

type
string

可选的邮箱类型，例如 WORK 或 HOME。

organization
string

联系人的可选组织名称。

title
string

联系人的可选职位名称。

link_preview
object

仅用于 message.type=link_preview，与 text 一起必填，不得混用其他载荷。公共结构仅要求 url；可选 title 和 description 允许空字符串，不允许 null。本 API 的 WhatsApp 发送策略额外要求非空 title/image_url，title 最多 255 个 Unicode 字符，description 最多 1024 个。

url
string

必填目标链接：带主机名且不含空白的绝对 HTTP(S) URI；方括号地址仅接受 IPv6 字面量。保留原文，不保证资源可访问。

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

title
string

可选预览标题，允许空字符串，不允许 null。WhatsApp 要求非空，且最多 255 个 Unicode 字符。

description
string

可选预览摘要，允许空字符串，不允许 null。WhatsApp 最多允许 1024 个 Unicode 字符。

image_url
string

可选图片 URI，WhatsApp 要求必填且非空。必须是带主机名且不含空白的绝对 HTTP(S) URI；方括号地址仅接受 IPv6 字面量。保留原文，不保证资源可访问。

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

poll
object

仅用于 message.type=poll 且必填；不得混用 text 或其他载荷。必须提供 question、options 和 max_selections。题目和选项标题保留原文。公共结构不限制题目长度、最大选项数量或标题重复；具体渠道可有额外限制。

question
string

必填投票题目，须包含非空白字符，保留原文。

minLength: 1 · pattern: \S

options[]
object[]

必填选项数组，至少两个选项，每项须有 title。

minItems: 2

title
string

必填选项标题，须包含非空白字符；发送时不 trim、不改大小写或 Unicode 形式。

minLength: 1 · pattern: \S

max_selections
integer

必填，每位投票者最多可选的选项数量，不是投票人数。必须为 1 到 options 数量之间的整数，由接口验证。1.0、1e0 等整数数值与 1 等价，非整数非法。

minimum: 1

reply_to
object

引用回复目标；把可引用消息事件的 data.message.reply_token 或发送响应的 data.reply_token 原样放入 reply_to.reply_token，使用原账号和会话，不可用消息 ID 替代。

reply_token
string

来自可引用消息事件 data.message.reply_token 或发送响应 data.reply_token 的不透明句柄；按原账号及会话原样使用，不可用消息 ID 替代。

minLength: 1

mentions[]
object[]

群消息的 @ 目标列表。type=member 使用对应 Provider 的成员 id；type=all 表示 @所有人，仅在 Provider 支持时生效，否则返回 unsupported_message_type。

type
string

@ 目标类型。省略时按 member 处理以兼容旧请求；type=member 必须传 id，type=all 不传 id 且仅适用于群聊。

enum: member, all

id
string

type=member 时必填的 Provider 成员标识。

minLength: 1

如何理解结果

保存返回的 message_id 和 provider_ref，用于关联后续事件或排查。accepted 不表示已送达；仅在渠道支持回执时，通过对应事件确认送达。标识格式因渠道而异。

reply_token — WhatsApp 发送成功且引用上下文完整时可选返回的非空不透明句柄，包括新发送投票，普通文字可据此引用。不可用时省略，不改变 accepted 状态。按原账号及会话原样使用，它不是消息 ID。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "message_id": "msg_example",
    "account_id": "acc_example",
    "status": "accepted",
    "provider_ref": "provider_msg_example",
    "reply_token": "<opaque WhatsApp reply handle>"
  }
}

响应体

message_id
string

已受理消息的 UnifyPort 消息标识（msg_...）。

account_id
string

该响应所对应的渠道账号。

status
string

受理状态；accepted 表示消息已排队等待投递到渠道。

provider_ref
string

渠道侧消息引用，在渠道分配后返回。

reply_token
string

WhatsApp 发送成功且引用上下文完整时可选返回的非空不透明句柄，包括新发送投票，普通文字可据此引用。不可用时省略，不改变 accepted 状态。按原账号及会话原样使用，它不是消息 ID。

minLength: 1

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

409

冲突

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

500

服务端错误

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

501

渠道未实现

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

502

上游网关错误

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

失败后怎么处理

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

invalid_request · 10000 · 400
检查必填字段、格式和渠道条件，修正请求后再调用。
missing_api_key · 11000 · 401
检查 X-Api-Key 是否正确、工作区是否有效。
invalid_api_key · 11001 · 401
检查 X-Api-Key 是否正确、工作区是否有效。
provider_not_ready · 30009 · 409
检查授权和运行态，恢复连接后先确认上次操作结果，再决定是否重试。
unsupported_message_type · 36000 · 400
选择渠道支持的操作或消息类型，重复请求不会增加渠道能力。
invalid_reply_token · 36006 · 400
原样复制入站 reply_token，不要用消息 ID 构造。引用回复需要支持该能力的渠道。