15. 融云 API 15.6 偶像端消息收件箱【基础探测通过，待数据联调】

Table of Contents

15.6 偶像端消息收件箱【基础探测通过，待数据联调】

GET /tieup/api/v1/artist/message-inbox

查询参数：

参数 类型 必填 说明
page integer 否 页码，默认 1
page_size integer 否 每页数量，默认 20

鉴权：需要 Authorization: Bearer <access_token>，当前账号必须已开通偶像端。

数据按粉丝聚合，返回粉丝资料、未读数、最后消息、订阅过期时间等。最后消息按 sent_at DESC, id DESC 选择当前偶像身份未删除的最新定向消息，允许正常发送成功消息和已撤回消息；撤回后保留原消息位置，不回退到更早的普通消息。 响应字段：

字段 类型 说明
items array 当前页数据列表
items[].fan_user_id integer 粉丝用户 ID
items[].fan_nickname string 粉丝当前昵称
items[].fan_avatar string 粉丝当前头像，无值返回空字符串
items[].fan_online_status integer 粉丝在线状态
items[].rong_ultra_group_id string 当前偶像融云超级群 ID
items[].is_current_fan integer 当前是否仍为有效订阅粉丝
items[].subscription_expires_at string/null 当前聚合记录中的订阅到期时间
items[].last_message object/null 最后一条当前身份可见消息，字段格式与“偶像端全群消息列表”一致；无消息时为 null
items[].last_message.message_no string 本地消息编号
items[].last_message.direction integer 本地业务消息方向：1=粉丝发偶像，2=偶像定向回复粉丝
items[].last_message.conversationType integer 融云超级群会话类型，固定为 10
items[].last_message.targetId string 融云超级群 ID
items[].last_message.channelId string 融云超级群频道 ID
items[].last_message.messageId integer 本地消息表 ID
items[].last_message.messageDirection integer 偶像视角消息方向：1=当前偶像发送，2=当前偶像接收
items[].last_message.senderUserId string 发送者融云用户 ID
items[].last_message.sentStatus integer 融云发送状态；正常成功或已撤回均为 30
items[].last_message.receivedTime integer 接收时间，毫秒时间戳
items[].last_message.sentTime integer 发送时间，毫秒时间戳
items[].last_message.objectName string 原消息融云 ObjectName，撤回后保持不变
items[].last_message.content object 消息正文；撤回消息返回空对象 {}
items[].last_message.content.content string 文本消息正文，仅 RC:TxtMsg 返回
items[].last_message.content.imageUri string 图片原图 URL，仅 RC:ImgMsg 返回
items[].last_message.content.remoteUrl string 语音 URL，仅 RC:HQVCMsg 返回
items[].last_message.content.sightUrl string 视频 URL，仅 RC:SightMsg 返回
items[].last_message.content.duration integer 语音或视频时长，单位秒
items[].last_message.content.size string 视频文件大小，单位字节
items[].last_message.content.name string 语音或视频原始文件名
items[].last_message.messageUId string 融云服务端消息唯一 ID
items[].last_message.canIncludeExpansion boolean 存在扩展快照且消息发送成功、未撤回、具备融云 UID 时返回 true，否则返回 false
items[].last_message.expansionDic object 发送时扩展快照；普通粉丝消息在本地查询时批量覆盖当前画像和 replyCount，定向消息追加 is_read
items[].last_message.expansionDic.is_read string 定向消息接收方实际已读状态：true 或 false
items[].last_message.directedUserIds array 定向接收融云用户 ID 列表
items[].last_message.disableUpdateLastMessage boolean 当前固定为 false
items[].last_message.quoteInfo object 引用消息信息，无引用时为空对象
items[].last_message.quoteInfo.messageUId string 被引用消息融云 UID
items[].last_message.quoteInfo.senderId string 被引用消息发送者融云用户 ID
items[].last_message.quoteInfo.objectName string 被引用消息 ObjectName
items[].last_message.quoteInfo.quoteMessageStatus integer 被引用消息状态：0=正常，1=已撤回
items[].last_message.originMessage object 当前偶像可见的引用原消息，无可见原消息时为空对象
items[].last_message.originMessage.senderNickname string 被引用原消息发送者当前昵称
items[].last_message.originMessage.content object 被引用原消息正文；原消息已撤回时为空对象 {}
items[].last_message.originMessage.content.content string 被引用文本消息正文
items[].last_message.originMessage.content.imageUri string 被引用图片消息原图 URL
items[].last_message.originMessage.content.remoteUrl string 被引用语音消息 URL
items[].last_message.originMessage.content.sightUrl string 被引用视频消息 URL
items[].last_message.originMessage.content.duration integer 被引用语音或视频时长，单位秒
items[].last_message.originMessage.content.size string 被引用视频文件大小，单位字节
items[].last_message.originMessage.content.name string 被引用语音或视频原始文件名
items[].last_message.readReceiptInfo object 偶像视角已读回执；撤回消息不参与已读统计
items[].last_message.readReceiptInfo.isReceiptRequestMessage boolean 正常发送成功且未撤回时为 true，撤回消息为 false
items[].last_message.readReceiptInfo.hasRespond boolean 当前偶像作为接收方时是否已读，撤回消息为 false
items[].last_message.readReceiptInfo.userIdList object 当前固定返回空对象 {}
items[].last_message_no string/null 兼容旧客户端的最后消息编号
items[].last_message_direction integer/null 兼容旧客户端的最后消息方向
items[].last_message_type string/null 兼容旧客户端的最后消息业务类型
items[].last_message_at string/null 兼容旧客户端的最后消息时间
items[].unread_count integer 偶像未读粉丝消息数，只统计发送成功、未撤回且不是订阅业务消息（message_type=subscription 或 object_name=Tieup:Subscribe）的消息
items[].fan_message_count integer 粉丝累计有效消息数
items[].artist_reply_count integer 偶像累计回复数
pagination.page integer 当前页码
pagination.page_size integer 每页数量
pagination.total integer 总数量
pagination.next_cursor string/null 游标分页预留，当前为 null

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "items": [
      {
        "fan_user_id": 10001,
        "fan_nickname": "Tieup用户",
        "fan_avatar": "https://cdn.example.com/fan.png",
        "fan_online_status": 1,
        "rong_ultra_group_id": "tieup_artist_group_20001",
        "is_current_fan": 1,
        "subscription_expires_at": "2026-08-01 00:00:00",
        "last_message": {
          "message_no": "MSG2026070610300012345678",
          "direction": 1,
          "conversationType": 10,
          "targetId": "tieup_artist_group_20001",
          "channelId": "",
          "messageId": 456,
          "messageDirection": 2,
          "senderUserId": "tieup_fan_10001",
          "sentStatus": 30,
          "receivedTime": 1783314600000,
          "sentTime": 1783314600000,
          "objectName": "RC:TxtMsg",
          "content": {},
          "messageUId": "XXXX-JJJJ-KKKK",
          "canIncludeExpansion": true,
          "expansionDic": {
            "senderRole": "fan",
            "fanId": "10001",
            "artistId": "20001",
            "is_read": "false"
          },
          "directedUserIds": [
            "tieup_artist_20001"
          ],
          "disableUpdateLastMessage": false,
          "quoteInfo": {},
          "originMessage": {},
          "readReceiptInfo": {
            "isReceiptRequestMessage": false,
            "hasRespond": false,
            "userIdList": {}
          }
        },
        "last_message_no": "MSG2026070610300012345678",
        "last_message_direction": 1,
        "last_message_type": "text",
        "last_message_at": "2026-07-06 10:30:00",
        "unread_count": 0,
        "fan_message_count": 3,
        "artist_reply_count": 2
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "next_cursor": null
    }
  }
}

说明：last_message 不触发自动已读。最后消息已撤回时，接口继续返回原消息编号、方向、类型和时间，正文返回空对象 {}，客户端可展示“消息已撤回”；撤回消息不计入 unread_count，也不参与已读回执。last_message_no 等旧摘要字段继续保留，值与完整 last_message 对应。