消息

发送名片（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

调用前准备

在服务端使用资源所属工作区的 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。发送给新收件方时遵循对应渠道的标识规则。统一消息发送能力

请求

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

请求参数

请求头

X-Api-Key

string必填

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

Content-Type

string必填

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

请求体

account_id

string必填

发送该消息的渠道账号。

minLength: 1

to

object必填

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

id

string必填

收件方在渠道侧的标识。

minLength: 1

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 时必填的非空文本。

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

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

minLength: 1

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

联系人的可选职位名称。

provider_data

object

渠道专属选项，例如 Telegram 的 parse_mode；WhatsApp audio / video 的 seconds 使用非负整数，仅在 video 时，取值范围为 0 到 4294967295；waveform 仅适用于 audio。引用回复请使用顶层 reply_to。

seconds

integer

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

minimum: 0

waveform

string

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

reply_to

object

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

reply_token

string

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

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

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

409

冲突

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

500

服务端错误

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

501

渠道未实现

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

502

上游网关错误

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

失败后怎么处理

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

invalid_request · 10000 · 400: 检查必填字段、格式和渠道条件，修正请求后再调用。
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 构造。引用回复需要支持该能力的渠道。