From 8539abd12f9171d7912922a2cff4ea9eae12213d Mon Sep 17 00:00:00 2001 From: wuziqian211 <65224318+wuziqian211@users.noreply.github.com> Date: Mon, 1 Apr 2024 01:14:39 +0800 Subject: [PATCH] add more docs --- docs/message/private_msg.md | 45 +++++- docs/message/private_msg_content.md | 209 ++++++++++++++++++++++++++-- 2 files changed, 236 insertions(+), 18 deletions(-) diff --git a/docs/message/private_msg.md b/docs/message/private_msg.md index 811375f..d0b68a7 100644 --- a/docs/message/private_msg.md +++ b/docs/message/private_msg.md @@ -4,7 +4,42 @@ ### 会话对象 -待补充…… +| 字段 | 类型 | 内容 | 备注 | +| -------------------- | ---- | -------------- | -------------------------------------------------------------- | +| talker_id | num | 聊天对象的id | `session_type` 为 `1` 时表示用户 mid，为 `2` 时表示粉丝团 id | +| session_type | num | 聊天对象的类型 | 1：用户
2：粉丝团 | +| at_seqno | num | 最近一次未读at自己的消息的序列号 | 在粉丝团时有效，若没有未读的at自己的消息则为`0` | +| top_ts | num | | | +| group_name | str | 粉丝团名称 | 在粉丝团时有效 | +| group_cover | str | 粉丝团头像 | 在粉丝团时有效 | +| is_follow | num | 是否已关注对方 | 在用户会话中有效 | +| is_dnd | num | 是否设置了免打扰 | | +| ack_seqno | num | 最近一次已读的消息序列号 | | +| ack_ts | num | 最近一次已读时间 | 微秒级时间戳| +| session_ts | num | 会话时间 | 微秒级时间戳| +| unread_count | num | 未读消息数 | | +| last_msg | obj | 最近的一条消息 | 详见[私信主体对象](#私信主体对象) | +| group_type | num | 粉丝团类型 | 在粉丝团时有效
0：应援团
2：官方群 | +| can_fold | num | | | +| status | num | 会话状态 | | +| max_seqno | num | 最近一条消息的序列号 | | +| new_push_msg | num | 是否有新推送的消息 | | +| setting | num | | | +| is_guardian | num | | | +| is_intercept | num | 是否被拦截 | | +| is_trust | num | 是否不拦截此会话 | | +| system_msg_type | num | 系统消息类型 | 0：不是系统消息
7：UP主小助手 | +| account_info | obj | 会话信息 | 仅在系统消息中出现 | +| live_status | num | 是否正在直播 | | +| biz_msg_unread_count | num | 未读推送消息数 | | +| user_label | null | | | + +`account_info`对象： + +| 字段 | 类型 | 内容 | 备注 | +| ------- | ---- | -------- | ---- | +| name | str | 会话名称 | | +| pic_url | str | 会话头像 | | ### 私信主体对象 @@ -14,7 +49,7 @@ | ---------------- | ---- | -------------- | -------------------------------------------------------------- | | sender_uid | num | 发送者mid | | | receiver_type | num | 接收者类型 | 1：用户
2：粉丝团 | -| receiver_id | num | 接收者id | `receiver_type` 为 `1` 时表示用户 mid，为 `2` 时表示应援团 id | +| receiver_id | num | 接收者id | `receiver_type` 为 `1` 时表示用户 mid，为 `2` 时表示粉丝团 id | | msg_type | num | 消息类型 | 详见[私信消息类型、内容说明](private_msg_content.md) | | content | str | 消息内容 | [私信内容对象](private_msg_content.md)经过 JSON 序列化后的文本 | | msg_seqno | num | 消息序列号 | 按照时间顺序从小到大 | @@ -52,7 +87,7 @@ | 10 | 自动回复 - 关键词回复 | | | 11 | 自动回复 - 大航海上船回复 | | | 12 | 自动推送 - UP 主赠言 | 在以前稿件的自动推送与其附带的 UP 主赠言是 2 条不同的私信（其中 UP 主赠言的消息来源代码为 12），现在 UP 主赠言已被合并成为稿件自动推送的一部分 | -| 13 | 应援团系统提示 | 如：应援团中的提示信息“欢迎xxx入群” | +| 13 | 粉丝团系统提示 | 如：粉丝团中的提示信息“欢迎xxx入群” | | 16 | （？） | **作用尚不明确** | | 17 | 互相关注 | 互相关注时自动发送的私信“我们已互相关注，开始聊天吧~” | | 18 | 系统提示 | 如：“对方主动回复或关注你前，最多发送1条消息” | @@ -138,7 +173,7 @@ curl 'https://api.vc.bilibili.com/session_svr/v1/session_svr/single_unread' \ | 参数名 | 类型 | 内容 | 必要性 | 备注 | | ----------------- | ---- | ---------------- | ------ | ------------------------------------------------------ | -| talker_id | num | 聊天对象的id | 必要 | `session_type` 为 `1` 时表示用户 mid，为 `2` 时表示应援团 id | +| talker_id | num | 聊天对象的id | 必要 | `session_type` 为 `1` 时表示用户 mid，为 `2` 时表示粉丝团 id | | session_type | num | 聊天对象的类型 | 必要 | 1：用户
2：粉丝团 | | size | num | 返回消息数量 | 非必要 | 默认为 20，最大为 200 | | begin_seqno | num | 开始的序列号 | 非必要 | 提供本参数时返回以本序列号开始（不包括本序列号）的消息 | @@ -284,7 +319,7 @@ curl -G 'https://api.vc.bilibili.com/svr_sync/v1/svr_sync/fetch_session_msgs' \ | 参数名 | 类型 | 内容 | 必要性 | 备注 | | --------------------- | ---- | ------------------------ | ------ | ---------------------------------------------------- | | msg[sender_uid] | num | 发送者mid | 必要 | 必须为自己的 mid | -| msg[receiver_id] | num | 接收者id | 必要 | `msg[receiver_type]` 为 `1` 时表示用户 mid，为 `2` 时表示应援团 id | +| msg[receiver_id] | num | 接收者id | 必要 | `msg[receiver_type]` 为 `1` 时表示用户 mid，为 `2` 时表示粉丝团 id | | msg[receiver_type] | num | 接收者类型 | 必要 | 1：用户
2：粉丝团 | | msg[msg_type] | num | 消息类型 | 必要 | 详见[私信消息类型、内容说明](private_msg_content.md) | | msg[msg_status] | num | 消息状态 | 非必要 | 恒为 `0` | diff --git a/docs/message/private_msg_content.md b/docs/message/private_msg_content.md index fb33b9e..584bbf2 100644 --- a/docs/message/private_msg_content.md +++ b/docs/message/private_msg_content.md @@ -28,6 +28,8 @@ 在发送私信时，请确保下面的对象合法且 `url` 项的值为 B 站的图床 url，否则会报 21037 `图片格式不合法，不要调戏接口啦` 错误 +建议设置 `height` 与 `width` 属性，否则可能会导致消息显示异常 + 根对象： | 字段 | 类型 | 内容 | 备注 | @@ -58,7 +60,7 @@ 内容为目标私信的 `msg_key` -请确保目标私信存在、在撤回有效期（120 秒）里，且与发送的私信在同一会话内；成功发送此私信后，目标私信的 `msg_status` 会变成 `1` +请确保目标私信存在、在撤回有效期（120 秒）里，且与发送的私信在同一会话内；成功发送此私信后，目标私信的 `msg_status` 会变成 `1`（在前端会显示目标消息被撤回） **示例：** @@ -68,7 +70,7 @@ 7345551441311046575 ``` -若发送成功，则私信 A 会被撤回，并且其 `msg_status` 也会变成 `1` +若发送成功，则私信 A 会被撤回（在前端显示该消息被撤回），并且其 `msg_status` 也会变成 `1` ## 自定义表情消息（`msg_type=6`） @@ -83,7 +85,7 @@ | author | str | 分享内容作者 | 此项不实时更新，在发送私信时设置（非必要） | | headline | str | 分享内容主标题 | 比 `title` 更突出；此项不实时更新，在发送私信时设置（非必要） | | id | num | 分享内容id | | -| source | num | 分享内容类型 | ~~1：小视频~~（已弃用）
2：相簿
3：纯文字
4：直播
5：视频
6：专栏
7：番剧（`id` 为 season_id）
8：音乐
9：国产动画（`id` 为 AV 号）
10：图片
11：动态
16：番剧（`id` 为 epid）
17：番剧 | +| source | num | 分享内容类型 | ~~1：小视频~~（已弃用）
2：相簿
3：纯文字
4：直播（此类型不常用，见[分享其他内容消息](#分享其他内容消息msg_type14)）
5：视频
6：专栏
7：番剧（`id` 为 season_id）
8：音乐
9：国产动画（`id` 为 AV 号）
10：图片
11：动态
16：番剧（`id` 为 epid）
17：番剧 | | source_desc | str | 分享内容类型说明 | 仅当 `source` 值为 `16` 时有此项 | | thumb | str | 分享内容封面 | 此项不实时更新，在发送私信时设置 | | title | str | 分享内容标题 | 此项不实时更新，在发送私信时设置 | @@ -92,6 +94,8 @@ **示例：** +分享 UP 主 “社会易姐QwQ” 的视频 av246551172 + ```json { "author": "社会易姐QwQ", @@ -106,6 +110,8 @@ ### 小程序消息（`msg_type=9`） +由于 B 站并没有对外公开小程序，此消息类型不常用 + 根对象： | 字段 | 类型 | 内容 | 备注 | @@ -121,6 +127,8 @@ **示例：** +分享 “主站测试专用小程序” + ```json { "avatar": "http://i0.hdslb.com/bfs/mall/mall/7b/dd/7bdd072290de017593791b52e937ca29.png", @@ -138,27 +146,80 @@ 此类型消息仅可接收，不可直接发送 +**按钮显示逻辑说明：** + +- **按钮的url：**首先尝试读取 `jump_uri_*_config` 对象中表示当前设备类型的 url（如 `web_uri`、`android_uri` 等）；若为空值，则尝试读取 `jump_uri_*_config` 对象中 `all_uri` 的值；若仍为空值，则读取根对象中 `jump_uri_*` 的值；若仍为空值，则不显示该按钮（无论 `jump_text_*` 或 `jump_uri_*_config` 中的 `text` 是否为非空值） +- **按钮提示文字：**若按钮是可见的，则先尝试读取 `jump_uri_*_config` 对象中 `text` 的值；若为空值，则读取根对象中 `jump_text_*` 的值；若仍为空值，则提示文字为 `查看详情` + 根对象： | 字段 | 类型 | 内容 | 备注 | | ----------------- | ----- | ------------- | ------------------------- | | title | str | 通知标题 | | | text | str | 通知内容 | | -| jump_text | str | 按钮1提示文字 | | -| jump_uri | str | 按钮1跳转链接 | | -| modules | array | 详细信息 | | -| jump_text_2 | str | 按钮2提示文字 | | -| jump_uri_2 | str | 按钮2跳转链接 | | -| jump_text_3 | str | 按钮3提示文字 | | -| jump_uri_3 | str | 按钮3跳转链接 | | -| notifier | obj | 发送者信息 | | +| jump_text | str | 按钮1提示文字 | 若按钮1不存在则为空；若按钮1存在此项也可能为空，此时前端显示文字为 `查看详情` | +| jump_uri | str | 按钮1跳转链接 | 若按钮1不存在则为空 | +| modules | 有效时：array
无效时：null | 详细信息 | | +| jump_text_2 | str | 按钮2提示文字 | 若按钮2不存在则为空；若按钮2存在此项也可能为空，此时前端显示文字为 `查看详情` | +| jump_uri_2 | str | 按钮2跳转链接 | 若按钮2不存在则为空 | +| jump_text_3 | str | 按钮3提示文字 | 若按钮3不存在则为空；若按钮3存在此项也可能为空，此时前端显示文字为 `查看详情` | +| jump_uri_3 | str | 按钮3跳转链接 | 若按钮3不存在则为空 | +| notifier | 有效时：obj
无效时：null | 发送者信息 | | | jump_uri_config | obj | 按钮1配置 | | | jump_uri_2_config | obj | 按钮2配置 | | | jump_uri_3_config | obj | 按钮3配置 | | -| biz_content | obj | 扩展信息 | | +| biz_content | 有效时：obj
无效时：null | 扩展信息 | | + +`modules`数组： + +| 项 | 类型 | 内容 | 备注 | +| ---- | ---- | ------------- | ---- | +| 0 | obj | 详细信息1 | | +| n | obj | 详细信息(n+1) | | +| …… | obj | …… | …… | + +`modules`数组中的对象： + +| 字段 | 类型 | 内容 | 备注 | +| ------ | ---- | ---- | ---- | +| title | str | 标题 | | +| detail | str | 内容 | | + +`notifier`对象： + +| 字段 | 类型 | 内容 | 备注 | +| ---------- | ---- | ---------- | ------ | +| avatar_url | str | 发送者头像 | | +| nickname | str | 发送者名称 | | +| jump_url | str | 发送者链接 | 可为空 | + +`jump_uri_config`、`jump_uri_2_config`、`jump_uri_3_config`对象： + +| 字段 | 类型 | 内容 | 备注 | +| ----------- | ---- | ----------------------- | -------------------- | +| all_uri | str | 所有设备的跳转链接 | 若按钮不存在则无此项 | +| android_uri | str | Android客户端的跳转链接 | 若按钮不存在则无此项 | +| iphone_uri | str | iPhone客户端的跳转链接 | 若按钮不存在则无此项 | +| ipad_uri | str | iPad客户端的跳转链接 | 若按钮不存在则无此项 | +| web_uri | str | 网页上的跳转链接 | 若按钮不存在则无此项 | +| text | str | 按钮提示文字 | 若按钮不存在则为空 | + +`biz_content`对象： + +| 字段 | 类型 | 内容 | 备注 | +| ------------ | ---- | ----------- | ---------------- | +| cover | str | 封面url | | +| backup_cover | str | 备用封面url | | +| refresh_type | num | （？） | **作用尚不明确** | +| biz_type | num | （？） | **作用尚不明确** | +| biz_id1 | str | （？） | **作用尚不明确** | +| biz_id2 | str | （？） | **作用尚不明确** | +| biz_status | num | （？） | **作用尚不明确** | **示例：** +直播开始提醒 + ```json { "title": "直播开始提醒", @@ -222,8 +283,17 @@ | pub_date | num | 视频发布时间 | 秒级时间戳，若视频失效则为 `0` | | attach_msg | 有效时：obj
无效时：null | UP主赠言 | | +`attach_msg`对象： + +| 字段 | 类型 | 内容 | 备注 | +| ------- | ---- | -------- | ---------------------------------------------- | +| id | num | 赠言id | | +| content | str | 赠言内容 | 会自动加上 `UP主赠言：` 前缀，可能包含私信表情 | + **示例：** +推送视频 av740817783/BV1Dk4y1E7MZ + ```json { "title": "【2023嵌入式大赛】浅浅测试一下龙芯开发板", @@ -260,8 +330,17 @@ | attach_msg | 有效时：obj
无效时：null | UP主赠言 | | | pub_date | num | 专栏发布时间 | 秒级时间戳，若专栏失效则为 `0` | +`attach_msg`对象： + +| 字段 | 类型 | 内容 | 备注 | +| ------- | ---- | -------- | ---------------------------------------------- | +| id | num | 赠言id | | +| content | str | 赠言内容 | 会自动加上 `UP主赠言：` 前缀，可能包含私信表情 | + **示例：** +推送专栏 cv18275013 + ```json { "rid": 18275013, @@ -303,8 +382,71 @@ } ``` +### 分享其他内容消息（`msg_type=14`） + +常见于分享直播 + +根对象： + +| 字段 | 类型 | 内容 | 备注 | +| ------ | ---- | ---------------- | -------------------------------- | +| author | str | 分享内容作者 | 此项不实时更新，在发送私信时设置 | +| cover | str | 分享内容封面 | 此项不实时更新，在发送私信时设置 | +| desc | str | 分享内容简介 | 此项不实时更新，在发送私信时设置 | +| source | str | 分享内容类型说明 | 常见的值为 `直播` | +| title | str | 分享内容标题 | 此项不实时更新，在发送私信时设置 | +| url | str | 分享内容url | | + +**示例：** + +分享直播 ID 21738461 + +```json +{ + "author": "哔哩哔哩晚会", + "cover": "https://i1.hdslb.com/bfs/face/1b593d28fcd0cf63837c3ea80ac96d01bb85ec3b.jpg", + "desc": "主播：哔哩哔哩晚会 https://live.bilibili.com/21738461", + "source": "直播", + "title": "2023最美的夜 bilibili晚会", + "url": "https://live.bilibili.com/21738461?broadcast_type=0&is_room_feed=1&live_from=41000&share_medium=android&share_source=bili_message&bbid=XU8CE838022AF6625C64B2153A3EF1E571AFF&ts=1704038936971" +} +``` + ### 被关注时的自动推送消息（`msg_type=16`） +一般仅在开启了 B 站的 “被关注回复” 功能与勾选 “被关注后，向关注我的人推送我的往期作品” 选项（仅部分用户会显示此选项）时才会发送此类型消息，紧接在自动发送的文字消息其后 + +根对象： + +| 字段 | 类型 | 内容 | 备注 | +| ------------- | ----- | ---------------- | ------------------------------------ | +| main_title | str | 主标题 | 一般为 `更多宝藏内容` | +| reply_content | str | 自动回复文字内容 | 仅显示在聊天列表，在私信内容中不显示 | +| sub_cards | array | 推送的作品列表 | 一般为3个 | + +`sub_cards`数组： + +| 项 | 类型 | 内容 | 备注 | +| ---- | ---- | --------- | ---- | +| 0 | obj | 作品1 | | +| n | obj | 作品(n+1) | | +| …… | obj | …… | …… | + +`sub_cards`数组中的对象： + +| 字段 | 类型 | 内容 | 备注 | +| --------- | ---- | ------------ | -------------------------------------------------------------- | +| card_id | num | 作品id | 当作品为视频时：表示AV号
当作品为专栏时：表示CV号 | +| card_type | num | 作品类型 | 1：视频 | +| jump_url | str | 作品链接 | | +| cover_url | str | 作品封面url | | +| field1 | str | 作品标题 | | +| field2 | str | 作品发布时间 | 格式：`YYYY-MM-DD` | +| field3 | str | 字段3 | 当作品为视频时：表示作品播放量
当作品为专栏时：表示阅读量 | +| icon3 | num | 图标3类型 | 1：播放量 | +| field4 | str | 字段4 | 当作品为视频时：表示作品弹幕数
当作品为专栏时：表示评论数 | +| icon4 | num | 图标4类型 | 3：弹幕数 | + **示例：** ```json @@ -350,7 +492,7 @@ ### 系统提示消息（`msg_type=18`） -此类型消息仅可接收，不可直接发送 +此类型消息仅可接收，不可直接发送；由系统自动发送，但仅自己可见 根对象： @@ -376,6 +518,8 @@ **示例：** +若自己与对方从未聊过天，且对方未关注自己，则会有系统提示 + ```json { "content": "[{\"text\":\"对方主动回复或关注你前，最多发送1条消息\",\"color_day\":\"#9499A0\",\"color_nig\":\"#9499A0\"}]" @@ -386,4 +530,43 @@ 以下消息类型仅常见于粉丝团中的系统消息（`receiver_type` 为 `2` 且 `sender_uid` 为 `0`） +### 成员入群消息（`msg_type=301`） +### 成员退群消息（`msg_type=302`） + +### 粉丝团冻结消息（`msg_type=303`） + +### 粉丝团解散消息（`msg_type=304`） + +### 粉丝团开通消息（`msg_type=305`） + +### 成员入群消息（`msg_type=306`） + +以上6种消息类型均为以下数据类型结构 + +根对象： + +| 字段 | 类型 | 内容 | 备注 | +| -------- | ---- | -------- | ---- | +| group_id | num | 粉丝团id | | +| content | str | 提示文字 | | + +**示例：** + +`社会易姐QwQ的应援团` 开通的消息 + +```json +{ + "group_id": 221082140, + "content": "社会易姐QwQ的应援团开通啦 (>▽<)" +} +``` + +成员 `wuziqian211` 进入 `社会易姐QwQ的应援团` 的消息 + +```json +{ + "group_id": 221082140, + "content": "欢迎wuziqian211入群" +} +```