API 参考

消息

置顶 / 取消置顶消息

置顶或取消置顶会话内的单条消息。标识符来自 message.received webhook 事件：conversation_id = data.conversation.id，message_id = data.message.id，sender_id = data.sender.id。sender_id 可选，缺省为账号自身。pinned=true 置顶（可选 duration_seconds 时长），pinned=false 取消置顶。

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

调用前准备

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

请求参数

请求头

X-Api-Key
string必填

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

Content-Type
string必填

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

请求体

account_id
string必填

执行动作的账号。

conversation_id
string必填

目标会话标识。

message_id
string必填

目标消息标识。

sender_id
string

原消息发送者标识；仅在操作账号自身消息时可以省略。

pinned
boolean必填

true 表示置顶，false 表示取消置顶。

duration_seconds
integer

可选的置顶时长，单位为秒。

format: uint32

如何理解结果

按文档解释响应字段和 HTTP 状态。204 成功响应没有响应体，排查时使用 X-Request-Id。下一步操作见相关链接。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "ok": true
  }
}

响应体

ok
boolean

操作成功时始终为 true；失败时返回非 2xx 状态码而非该字段。

响应

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 是否正确、工作区是否有效。