← API 参考
消息POST

发送名片（vCard）消息

发送名片消息。message.type 为 contact，message.contacts 是结构化名片数组（可一张或多张），由 UnifyPort 生成 vCard。每张名片必须有 name；phones[].number、emails[].address、organization、title 均可选。目前仅 WhatsApp 支持；contacts 为空或某张缺 name 返回 400 invalid_request，非 WhatsApp provider 返回 400 unsupported_message_type。 WhatsApp 发送成功且渠道提供可引用消息标识时可能返回的不透明回复句柄。必须原样回传，它不是父消息 id。

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

请求头

X-Api-Key
string必填

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

Content-Type
string必填

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

路径参数

该接口没有路径参数。

请求体

account_id
string必填

发送该消息的渠道账号。

to
object必填

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

id
string必填

收件方在渠道侧的标识。

type
string必填

收件方类型：user、group 或 channel。

enum: user, group, channel

message
object必填

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

type
string必填

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

enum: text, image, video, audio, document, file, contact

text
string

message.type 为 text 时发送的文本内容。

url
string

媒体消息使用的公开媒体 URL。

file_url
string

文件类渠道适配器支持的备用媒体 URL 字段。

file_key
string

渠道支持时使用的渠道侧或存储侧文件引用。

caption
string

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

contacts[]
object[]

message.type 为 contact 时发送的一张或多张结构化名片。

name
string

联系人显示名；每张名片都必须提供。

phones[]
object[]

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

number
string

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

type
string

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

emails[]
object[]

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

address
string

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

type
string

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

organization
string

联系人的可选组织名称。

title
string

联系人的可选职位名称。

provider_data
object

渠道专属选项，例如 Telegram 的 parse_mode，或 WhatsApp 音频的 seconds / waveform；引用回复请使用顶层 reply_to。

seconds
integer

WhatsApp audio 消息的可选音频时长，单位为秒，必须大于或等于 0。

waveform
string

WhatsApp audio 消息的可选音频波形数据字符串。

reply_to
object

引用回复目标；把入站 Webhook 的 data.message.reply_token 原样放入发送请求的 reply_to.reply_token。

reply_token
string

从入站 Webhook 的 data.message.reply_token 原样复制的不透明引用句柄。

mentions[]
object[]

在 text 或 caption 中由 {{@<id>}} 占位符引用的成员列表。

id
string

与对应 {{@<id>}} 占位符匹配的渠道侧成员标识。

响应体

message_id
string

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

account_id
string

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

status
string

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

provider_ref
string

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

reply_token
string

WhatsApp 发送成功且渠道提供可引用消息标识时可能返回的不透明回复句柄。必须原样回传，它不是父消息 id。

响应

200
200 OK

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

400
请求错误

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

401
未授权

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

409
冲突

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

500
服务端错误

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

501
渠道未实现

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

502
上游网关错误

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

请求

curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}'

响应

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