消息POST

发送文本消息

通过指定渠道账号发送标准化文本消息。message.text 必须非空；provider_data 承载 parse_mode 等渠道专属字段，引用回复使用顶层 reply_to。 WhatsApp 发送成功且渠道提供可引用消息标识时可能返回的不透明回复句柄。必须原样回传，它不是父消息 id。

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

请求头

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

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": "text",
    "text": "Hello from UnifyPort"
  },
  "provider_data": {
    "parse_mode": "markdown"
  }
}'

响应

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