15. 融云 API 15.3 粉丝端与偶像消息列表【基础探测通过，待数据联调】

Table of Contents

15.3 粉丝端与偶像消息列表【基础探测通过，待数据联调】

GET /tieup/api/v1/artists/{artist_id}/messages

路径参数：

参数 类型 必填 说明
artist_id integer 是 艺人 ID

查询参数：

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

鉴权：需要 Authorization: Bearer <access_token>。

说明：消息按 sent_at DESC, id DESC 倒序返回，优先返回最近发送成功或已撤回且本地已有发送时间的消息。本接口会先自动处理本页中当前粉丝接收的未读消息，再批量读取最终定向状态和群发实时人数，因此当前响应中的 expansionDic.is_read、readCount 已反映本次自动已读结果。

响应字段：

字段 类型 说明
items array 当前页数据列表
items[].message_no string 本地消息编号，用于已读、撤回等系统业务处理
items[].direction integer 本地业务消息方向：1=粉丝发偶像，2=偶像定向回复粉丝，3=偶像普通群发
items[].conversationType integer 融云超级群会话类型，当前固定返回 10
items[].targetId string 融云群 ID，对应本地 rong_ultra_group_id
items[].channelId string 融云超级群频道 ID，无频道返回空字符串
items[].messageId integer 本地消息表 ID
items[].messageDirection integer 粉丝视角消息方向：1=当前粉丝发送，2=当前粉丝接收
items[].senderUserId string 发送者融云用户 ID，来自 tieup_im_user_bind.rong_user_id；绑定缺失时返回空字符串
items[].sentStatus integer 融云发送状态：10=创建中，20=发送失败，30=发送成功或已撤回
items[].receivedTime integer 接收时间，毫秒时间戳；无发送时间返回 0
items[].sentTime integer 发送时间，毫秒时间戳；无发送时间返回 0
items[].objectName string 当前消息融云 ObjectName，如 RC:TxtMsg、RC:ImgMsg；新版引用回复保持真实消息类型
items[].content object 融云消息正文快照；媒体消息仅返回链接和必要元数据，不返回 Base64；消息已撤回时返回空对象 {}
items[].content.content string 仅文本消息返回文本正文；图片、语音、视频消息不返回该字段
items[].content.imageUri string 图片消息原图 URL，仅 RC:ImgMsg 返回
items[].content.remoteUrl string 语音消息 URL，仅 RC:HQVCMsg 返回
items[].content.sightUrl string 视频消息 URL，仅 RC:SightMsg 返回
items[].content.duration integer 语音或视频时长，单位秒
items[].content.size string 视频文件大小，单位字节
items[].content.name string 语音或视频原始文件名
items[].messageUId string 融云服务端消息唯一 ID，无值返回空字符串
items[].canIncludeExpansion boolean 返回扩展非空且消息发送成功、未撤回、具备融云 UID 时返回 true，否则返回 false
items[].expansionDic object 发送时扩展快照；普通粉丝消息在本地查询时批量覆盖当前画像与 replyCount，定向消息追加 is_read，群发消息追加 readCount、targetCount
items[].expansionDic.fanAvatar string 仅普通粉丝消息提供；当前粉丝头像
items[].expansionDic.fanNickname string 仅普通粉丝消息提供；当前粉丝昵称
items[].expansionDic.fanGender string 仅普通粉丝消息提供；"0"=未知、"1"=男、"2"=女
items[].expansionDic.companionStartAt string 当前连续陪伴段开始时间；无有效订阅为空字符串
items[].expansionDic.companionDays string 当前连续陪伴完整天数；无有效订阅为 "0"
items[].expansionDic.fanSubStatus string none、active 或 auto_renew_active
items[].expansionDic.fanSubAutoRenew string "0"=无有效订阅、"1"=自动续费、"2"=非自动续费
items[].expansionDic.fanSubExpiresAt string 当前连续有效订阅段最终到期时间；无有效订阅为空字符串
items[].expansionDic.fanSubExpiresText string 当前到期展示文案，无有效订阅为空字符串
items[].expansionDic.candySpent string 对当前艺人的有效糖果消费，固定两位小数
items[].expansionDic.lastArtistReplyAt string 艺人最后一次定向消息时间；无记录为空字符串
items[].expansionDic.lastArtistReplyText string 最近回复展示文案；无记录为空字符串
items[].expansionDic.replyCount string 当前消息历史引用回复次数，本地实时覆盖
items[].expansionDic.readCount string 仅群发消息提供，MySQL 与 Redis 实时人数的较大值，且不超过目标人数
items[].expansionDic.targetCount string 仅群发消息提供，原群发消息目标人数
items[].directedUserIds array 定向接收融云用户 ID 列表，无值返回空数组
items[].disableUpdateLastMessage boolean 是否不更新最后一条消息，当前固定返回 false
items[].quoteInfo object 引用消息信息；无引用时返回空对象 {}
items[].quoteInfo.messageUId string 被引用消息融云 UID
items[].quoteInfo.senderId string 被引用消息发送者融云用户 ID
items[].quoteInfo.objectName string 被引用消息 ObjectName
items[].quoteInfo.quoteMessageStatus integer 被引用消息状态：0=正常，1=已撤回
items[].originMessage object 当前粉丝可见的引用原消息展示信息；无引用、原消息缺失、不可见或已被当前粉丝身份删除时返回空对象 {}
items[].originMessage.senderNickname string 原消息发送者当前昵称；粉丝取用户昵称，艺人优先取艺名并回退用户昵称
items[].originMessage.content object 原消息主体；媒体消息不返回 Base64，原消息已撤回时返回空对象 {}
items[].originMessage.content.content string 原消息为文本时的正文；图片、语音、视频不返回该字段
items[].originMessage.content.imageUri string 原消息为图片时的原图 URL
items[].originMessage.content.remoteUrl string 原消息为语音时的远程 URL
items[].originMessage.content.sightUrl string 原消息为视频时的远程 URL
items[].originMessage.content.duration integer 原消息为语音或视频时的时长，单位秒
items[].originMessage.content.size string 原消息为视频时的文件大小，单位字节
items[].originMessage.content.name string 原消息为语音或视频时的原始文件名
items[].readReceiptInfo object 当前查看人视角的已读回执信息
items[].readReceiptInfo.isReceiptRequestMessage boolean 消息是否参与本地已读统计；发送成功且未撤回的定向或群发消息为 true
items[].readReceiptInfo.hasRespond boolean 当前查看人作为接收方时是否已读；发送方视角固定为 false
items[].readReceiptInfo.userIdList object 已读用户列表；历史列表当前固定返回空对象 {}，群发明细请使用群发已读统计接口
pagination.page integer 当前页码
pagination.page_size integer 每页数量
pagination.total integer 总数量
pagination.next_cursor string/null 游标分页预留字段，当前为空

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "items": [
      {
        "message_no": "MSG202607030002",
        "direction": 2,
        "conversationType": 10,
        "targetId": "tieup_artist_group_20001",
        "channelId": "",
        "messageId": 123,
        "messageDirection": 2,
        "senderUserId": "tieup_artist_20001",
        "sentStatus": 30,
        "receivedTime": 1783058400000,
        "sentTime": 1783058400000,
        "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": {}
        }
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "next_cursor": null
    }
  }
}

说明：消息列表以本地 tieup_im_message_stat + tieup_im_message_content 为准，长期保存正文、扩展快照和撤回状态，不依赖融云 7 天历史记录。items[] 的主体字段按根目录 融云响应字段参考.json 返回；仅额外保留 message_no、direction 供系统业务处理。有效订阅用户可同时看到该偶像普通群发元数据。服务端会在拉取当前页历史消息时自动处理本页可读消息：粉丝端会自动标记偶像定向消息和偶像群发消息。当前粉丝身份已执行用户侧删除的消息不返回，也不计入 pagination.total。图片、语音、视频响应只裁剪返回副本中的 Base64，数据库历史快照和实际发送给融云的载荷保持不变。