15. 融云 API 15.15 按融云消息 UID 查询单条消息【新增，待联调】

Table of Contents

15.15 按融云消息 UID 查询单条消息【新增，待联调】

POST /tieup/api/v1/im/messages/query
Authorization: Bearer <access_token>
Content-Type: application/json

鉴权：需要 APP 登录态。服务端从 Token 读取 current_identity，客户端不能指定粉丝或偶像身份。

请求字段：

字段 类型 必填 说明
message_uid string 是 需要查询的单条融云消息 UID，来自历史消息的 messageUId，最大 128 字符

完整请求示例：

{
  "message_uid": "ARTIST-REPLY-UID"
}

响应字段：

字段 类型 说明
code integer 响应码，成功为 200，消息不存在或不可见为 404
message string 响应提示
data object/array 成功时为单条消息对象；404 时为数组 []
data.message_no string 本地平台消息编号
data.direction integer 消息方向：1=粉丝发偶像，2=偶像定向回复粉丝，3=偶像普通群发
data.conversationType integer 融云超级群会话类型，固定为 10
data.targetId string 融云超级群 ID
data.channelId string 融云超级群频道 ID，无频道为空字符串
data.messageId integer 本地消息表 ID
data.messageDirection integer 当前身份视角方向：1=当前身份发送，2=当前身份接收
data.senderUserId string 发送者融云用户 ID，绑定缺失时为空字符串
data.senderNickname string 发送者当前昵称；粉丝取用户昵称，艺人优先取艺名并回退用户昵称
data.sentStatus integer 融云发送状态：30=发送成功或已撤回；本接口不返回创建中或发送失败消息
data.receivedTime integer 接收时间，毫秒时间戳
data.sentTime integer 发送时间，优先使用融云真实毫秒时间戳，历史缺失时回退本地发送时间
data.objectName string 融云消息 ObjectName
data.content object 消息主体；媒体消息不返回 Base64，消息已撤回时返回空对象 {}
data.content.content string 文本正文；图片、语音、视频不返回该字段
data.content.imageUri string 图片原图 URL，仅图片消息返回
data.content.remoteUrl string 语音远程 URL，仅语音消息返回
data.content.sightUrl string 视频远程 URL，仅视频消息返回
data.content.duration integer 语音或视频时长，单位秒
data.content.size string 视频文件大小，单位字节
data.content.name string 语音或视频原始文件名
data.messageUId string 融云消息 UID，与请求的 message_uid 对应
data.canIncludeExpansion boolean 存在扩展快照且消息发送成功、未撤回、具备融云 UID 时返回 true，否则返回 false
data.expansionDic object 发送时扩展快照；普通粉丝消息在本地查询时覆盖当前画像和 replyCount，定向消息追加 is_read，群发消息追加 readCount、targetCount
data.expansionDic.is_read string 定向消息接收方实际已读状态：true=已读，false=未读
data.expansionDic.readCount string 仅群发消息返回，当前实时已读人数
data.expansionDic.targetCount string 仅群发消息返回，群发目标人数
data.directedUserIds array 定向接收融云用户 ID 列表，无值为空数组
data.disableUpdateLastMessage boolean 是否不更新最后消息，当前固定为 false
data.quoteInfo object 引用定位信息；无引用时返回空对象 {}
data.quoteInfo.messageUId string 被引用原消息融云 UID
data.quoteInfo.senderId string 被引用原消息发送者融云用户 ID
data.quoteInfo.objectName string 被引用原消息 ObjectName
data.quoteInfo.quoteMessageStatus integer 被引用原消息状态：0=正常，1=已撤回
data.originMessage object 当前身份可见的引用原消息展示信息；无引用、不可见或已被当前身份删除时返回空对象 {}
data.originMessage.senderNickname string 原消息发送者当前昵称
data.originMessage.content object 原消息主体；媒体不返回 Base64，已撤回时返回空对象 {}；不继续递归展开原消息的引用
data.originMessage.content.content string 原消息文本正文
data.originMessage.content.imageUri string 原消息图片 URL
data.originMessage.content.remoteUrl string 原消息语音 URL
data.originMessage.content.sightUrl string 原消息视频 URL
data.originMessage.content.duration integer 原消息语音或视频时长，单位秒
data.originMessage.content.size string 原消息视频文件大小，单位字节
data.originMessage.content.name string 原消息语音或视频原始文件名
data.readReceiptInfo object 当前身份视角的已读回执信息
data.readReceiptInfo.isReceiptRequestMessage boolean 消息是否参与本地已读统计
data.readReceiptInfo.hasRespond boolean 当前身份作为接收方时是否已读；发送方视角固定为 false
data.readReceiptInfo.userIdList object 已读用户列表，当前固定为空对象 {}

完整成功响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "message_no": "MSG202607030002",
    "direction": 2,
    "conversationType": 10,
    "targetId": "tieup_artist_group_20001",
    "channelId": "",
    "messageId": 124,
    "messageDirection": 2,
    "senderUserId": "tieup_artist_20001",
    "sentStatus": 30,
    "receivedTime": 1783058460000,
    "sentTime": 1783058460000,
    "objectName": "RC:TxtMsg",
    "content": {
      "content": "收到，我会认真看完你的留言",
      "extra": ""
    },
    "messageUId": "ARTIST-REPLY-UID",
    "canIncludeExpansion": true,
    "expansionDic": {
      "senderRole": "artist",
      "artistId": "20001",
      "artistNickname": "示例艺人",
      "is_read": "false"
    },
    "directedUserIds": [
      "tieup_fan_10001"
    ],
    "disableUpdateLastMessage": false,
    "quoteInfo": {
      "messageUId": "BU2F-A9KJ-XXXX",
      "senderId": "tieup_fan_10001",
      "objectName": "RC:TxtMsg",
      "quoteMessageStatus": 0
    },
    "originMessage": {
      "senderNickname": "Tieup用户",
      "content": {
        "content": "你好，想和你分享今天发生的事",
        "extra": ""
      }
    },
    "readReceiptInfo": {
      "isReceiptRequestMessage": true,
      "hasRespond": false,
      "userIdList": {}
    },
    "senderNickname": "示例艺人"
  }
}

完整 404 响应示例：

{
  "code": 404,
  "message": "消息不存在或不可见",
  "data": []
}

说明：

  • 粉丝端只能查询本人定向消息，以及发送时间落在本人对该艺人任一订阅有效区间内的艺人普通群发；其他粉丝的定向消息不可查询。
  • 偶像端只能查询当前艺人超级群内的粉丝定向、艺人定向回复和艺人普通群发消息。
  • UID 不存在、超出当前身份权限或已被当前身份执行用户侧删除时统一返回相同的 404，不泄露消息是否真实存在。
  • 本接口只读取本地 tieup_im_message_stat 与 tieup_im_message_content，不调用融云历史接口，不自动标记已读，也不发送回执或队列任务。