# 消息类型与数据格式
注意
关于 markdown 的解析工作使用的库为 marked，不同解析库的解析结果会有细微的差异，为确保 markdown 消息发送后解析效果达到预期，请在发送之前使用 demo page 进行效果测试。
# 1、文本消息：
{
"msgtype": "text",
"text": {
"content": "你就是你, @150XXXXXXXX 璀璨的烟火"
},
"at": {
"atMobiles": [
"150********",
"186********"
],
"atWorkCodes": [
"171765"
],
"isAtAll": false
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：text【只有text、markdown类型的消息支持@】 |
| content | String | 是 | 消息内容，限制5000字符以内 |
| atMobiles | 否 | list | 被@人的手机号列表，手机号必须是合法的手机号 |
| atWorkCodes | 否 | list | 被@人的工号列表 |
| isAtAll | 否 | boolean | @所有人是true，否则为false |
# 2、markdown消息
注意事项：text字段里的链接为yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下
示例：yach://yach.zhiyinlou.com/session/webview?url=https%3a%2f%2fyach.zhiyinlou.com 如果PC端想要通过侧边栏打开的话，需要在上面的url链接后面，加上【pc_slide=true】
示例：yach://yach.zhiyinlou.com/session/webview?url=https%3a%2f%2fyach.zhiyinlou.com&pc_slide=true
评价消息的示例：yach://yach.zhiyinlou.com/session/robot?extra=%7B%22click%22:1%7D&type=appraise&nonce=1
消息回显：需要在上面链接的后面，新增【reply】参数把回显内容传过来，示例如下：
示例：yach://yach.zhiyinlou.com/session/robot?extra=%7B%22click%22:1%7D&reply=回显内容
为了防止一些图片在展示的时候发生闪动的现象，用户可以自己设定图片的宽高，按照如下格式设置：
{
"msgtype": "markdown",
"markdown": {
"title": "首屏会话透出的展示内容",
"image": "http://bpit-public.oss-cn-beijing.aliyuncs.com/note_1_1572593268.jpg",
"text": "# 这是支持markdown的文本 \n## 标题2 \n* 列表1 \n"
},
"image_size": {
"image_url_xxxxx": {
"h": 100,
"w": 100
}
}
}
{
"msgtype": "markdown",
"markdown": {
"title": "首屏会话透出的展示内容",
"image": "http://bpit-public.oss-cn-beijing.aliyuncs.com/note_1_1572593268.jpg",
"text": "# 这是支持markdown的文本 \n## 标题2 \n* 列表1 \n"
},
"at": {
"atMobiles": [
"150********",
"186********"
],
"atWorkCodes": [
"171765"
],
"isAtAll": false
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：markdown【只有text、markdown类型的消息支持@】 |
| title | String | 是 | 首屏会话透出的展示内容限制100个字符 |
| text | String | 是 | markdown格式的消息，限制5000字符以内 （目前markdown格式客户端展示有问题，如果需要在markdown里添加图片的话可以先用image字段替换） |
| image | String | 否 | 图片 url，图片比例要求 宽:高 = 2:1 |
| image_size | String | 否 | 指定图片的宽高 |
注意事项：可以给markdown消息正文中的图片配置跳转链接，配置跳转链接后将不再支持图片的放大预览，具体格式如下：
[](https://www.baidu.com)
如果markdown中使用html标签，为了各端展示一致，请不要使用超出以下范围的标签
字体大小颜色（红色正常16号文本）
粗体字体大小颜色（红色加粗16号文本）
下划线
删除线斜体
对齐方式
这是右对齐
这是居中对齐
这是居中对齐，
自定义颜色粗体+斜体+删除线
# 3、action_card
注意事项：single_url 、single_pc_url、single_mobile_url、action_url、action_pc_url、action_mobile_url 为 yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下
示例：yach://yach.zhiyinlou.com/session/webview?url=https%3a%2f%2fwww.taobao.com 如果PC端想要通过侧边栏打开的话，需要在上面的url链接后面，加上【pc_slide=true】
示例：yach://yach.zhiyinlou.com/session/webview?url=https%3a%2f%2fwww.taobao.com&pc_slide=true
如果PC端想要通过侧边栏打开后在右上角展示从浏览器打开的按钮，需要在上面的url链接后面，加上【browser_url=xxxxx】其中xxx为要在浏览器打开的地址，xxx需要进行urlencode
效果如下图：
btn_type字段的说明：
1：默认值，表示跳转链接
2：按钮，会触发请求url对应的接口地址（该接口需要在知音楼的白名单内），接入方的接口需要返回Json字符串，示例：{"code":200, "msg":"success"}
3：按钮，会触发机器人消息转发接口，比如评价消息的示例：yach://yach.zhiyinlou.com/session/robot?extra=%7B%22click%22:1%7D&type=appraise&nonce=1
6：按钮，唤起第三方独立应用，仅支持单个按钮的卡片消息（也就是仅支持single_url， 不支持btn_json_list），single_url为业务方应用的scheme地址
整体跳转示例：
{
"msgtype": "action_card",
"action_card": {
"title": "是透出到会话列表和通知的文案（整体跳转类型）",
"markdown": "支持markdown格式的正文内容",
"image": "http://bpit-public.oss-cn-beijing.aliyuncs.com/note_1_1572593268.jpg",
"content_title": "内容体title",
"single_title": "查看详情-侧边栏打开",
"single_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"single_pc_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"single_mobile_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"icon_url": "http://pic51.nipic.com/file/20141027/19767535_164340333430_2.jpg",
"btn_type": 1
},
"remind":{ // 提醒内容（目前仅支持action_card类型）
"title":"XXX通知",
"sub_title":"XXX通知",
"content":"XXX的周报",
"btn_type":1,
"btn_url":"yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下"
}
}
竖排按钮示例：
{
"msgtype": "action_card",
"action_card": {
"title": "是透出到会话列表和通知的文案（竖排按钮）",
"markdown": "支持markdown格式的正文内容",
"image": "http://bpit-public.oss-cn-beijing.aliyuncs.com/note_1_1572593268.jpg",
"content_title": "内容体title",
"btn_orientation": "0",
"btn_json_list": [
{
"title": "按钮名称-浏览器打开",
"action_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"action_pc_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"action_mobile_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"icon_url": "http://pic51.nipic.com/file/20141027/19767535_164340333430_2.jpg",
"btn_type": 1
},
{
"title": "按钮名称-侧边栏打开",
"action_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"icon_url": "http://pic51.nipic.com/file/20141027/19767535_164340333430_2.jpg",
"btn_type": 1
}
]
},
"remind":{ // 提醒内容（目前仅支持action_card类型）
"title":"XXX通知",
"sub_title":"XXX通知",
"content":"XXX的周报",
"btn_type":1,
"btn_url":"yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下"
}
}
横排按钮示例：
{
"msgtype": "action_card",
"action_card": {
"title": "是透出到会话列表和通知的文案（横排按钮）",
"markdown": "支持markdown格式的正文内容",
"image": "http://bpit-public.oss-cn-beijing.aliyuncs.com/note_1_1572593268.jpg",
"content_title": "内容体title",
"btn_orientation": "1",
"btn_json_list": [
{
"title": "按钮名称-浏览器打开",
"action_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"action_pc_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"action_mobile_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"icon_url": "http://pic51.nipic.com/file/20141027/19767535_164340333430_2.jpg",
"btn_type": 1
},
{
"title": "按钮名称-侧边栏打开",
"action_url": "yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下",
"icon_url": "http://pic51.nipic.com/file/20141027/19767535_164340333430_2.jpg",
"btn_type": 1
}
]
},
"remind":{ // 提醒内容（目前仅支持action_card类型）
"title":"XXX通知",
"sub_title":"XXX通知",
"content":"XXX的周报",
"btn_type":1,
"btn_url":"yach://yach.zhiyinlou.com/session/webview?url=这里放上接入方的跳转地址，记得提前url_encode编码一下"
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：action_card |
| title | String | 是 | 首屏会话透出的展示内容，限制100个字符 |
| content_title | String | 否 | 内容体title |
| markdown | String | 是 | 内容体content，限制5000字符以内 |
| btn_orientation | String | 否 | 使用独立跳转ActionCard样式时的按钮排列方式，竖直排列(0)，横向排列(1)；必须与btn_json_list同时设置 |
| single_title | String | 否 | 使用整体跳转ActionCard样式时的标题，必须与single_url同时设置，最长20个字符 |
| single_url | String | 否 | 消息点击链接地址 |
| single_pc_url | String | 否 | PC端消息点击链接的跳转地址，想与移动端区分跳转地址时候，可传该参数 |
| single_mobile_url | String | 否 | 移动端消息点击链接地址，想与PC端区分跳转地址时候，可传该参数 |
| icon_url | String | 否 | 按钮图标地址 |
| btn_type | String | 否 | 点击链接地址是否触发动作，默认不传 |
| btn_json_list | String | 否 | 使用独立跳转ActionCard样式时的按钮列表。 |
| image | String | 否 | 图片url |
| btn_json_list.title | String | 否 | 使用独立跳转ActionCard样式时的按钮的标题，最长20个字符。 |
| btn_json_list.action_url | String | 否 | 消息点击链接地址(不需要拼接知音楼前缀和urlencode |
| ) | |||
| btn_json_list.action_url | String | 否 | 消息点击链接地址 |
| btn_json_list.action_pc_url | String | 否 | PC端点击链接地址，想与移动端区分跳转地址时候，可传该参数 |
| btn_json_list.action_mobile_url | String | 否 | 移动端点击链接地址，想与PC端区分跳转地址时候，可传该参数 |
| btn_json_list.icon_url | String | 否 | 按钮图标地址 |
| btn_json_list.btn_type | String | 否 | 点击链接地址是否触发动作，默认不传 |
| remind.title | String | 否 | 提醒相关配置-标题 |
| remind.sub_title | String | 否 | 提醒相关配置-目前仅支持action_card类型-子标题 |
| remind.content | String | 否 | 提醒相关配置-目前仅支持action_card类型-提醒内容 |
| remind.btn_type | String | 否 | 提醒相关配置-目前仅支持action_card类型-触发动作类型（1：跳转链接） |
| remind.btn_url | String | 否 | 提醒相关配置-目前仅支持action_card类型-链接跳转地址，格式参考：single_url字段 |
# 4、图片消息：
{
"msgtype": "image",
"image": {
"url": "https://yach-static.zhiyinlou.com/yach/avatar1/18b85ab1eddf66dd5be67d62489db637_s120.jpg"
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：image |
| url | String | 是 | 图片链接 |
| width | String | 否 | 图片宽度 |
| height | String | 否 | 图片高度 |
| origin_url | String | 否 | 原图链接（如需点击查看原图则需要传该字段） |
| origin_width | String | 否 | 原图宽度 |
| origin_height | String | 否 | 原图高度 |
| file_name | String | 否 | 文件名称 |
| file_size | String | 否 | 文件大小 |
# 5、链接消息：
{
"msgtype": "link",
"link": {
"message_url": "",
"pic_url": "https://yach-static.zhiyinlou.com/yach/avatar1/18b85ab1eddf66dd5be67d62489db637_s120.jpg",
"title": "标题",
"text": "描述"
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：link |
| message_url | String | 是 | 消息点击链接地址 |
| pic_url | String | 是 | 图片地址 |
| title | String | 是 | 消息标题，建议100字符以内 |
| text | String | 是 | 消息描述，建议500字符以内 |
# 6、语音消息：
{
"msgtype": "audio",
"audio": {
"url": "https://yach-static.zhiyinlou.com/test/jsapi/222068/1590142961532/15abdf5b0fba92ec100cdbd145465d94/ec8e9914-98ff-4e7d-b8d1-8a38af431e33.aac",
"duration": 45,
"size": 10086,
"ext": "acc"
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：audio |
| url | String | 是 | 语音文件链接地址 |
| duration | Int | 是 | 正整数，小于60，表示音频时长，单位秒 |
| size | Int | 是 | 语音文件大小，单位KB |
| ext | String | 否 | 语音文件扩展名，示例：acc、amr |
# 7、文件消息（仅支持私聊、群聊）：
1、发送的文件地址必须是公网可访问的文件地址
2、备注说明：pdf文件需要传【https】的链接，否则IOS端无法预览
{
"msgtype": "file",
"file": {
"name": "WiFi接入手册.docx",
"url": "https://yach-xstatic.zhiyinlou.com/online/person/1597298085840/bjw5ix56lmt/****.docx",
"size": 967013
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：file |
| name | String | 是 | 文件名称 |
| url | String | 是 | 调用完腾讯cos之后拿到的文件链接 |
| size | String | 是 | 文件大小，单位Kb，文件大小必须填写，否则下载没有进度条，文件大小和文件一致，否则下载的文件会出现损坏不能打开 |
# 8、视频消息（仅支持私聊、群聊）：
1、发送该消息前，需要先调用获取腾讯云cos配置接口拿到腾讯云cos的临时密钥信息。
2、参考腾讯云对象存储SDK文档并下载对应的SDK，调用腾讯云的接口把业务方的图片、文件、视频上传到腾讯云。
3、拿到腾讯云接口返回的视频链接，再通过该消息类型发送到知音楼。
4、备注说明：不使用腾讯云对象存储进行视频上传的话，duration、size字段为必传参数，否则视频展示及播放可能会有未知问题。
{
"msgtype": "video",
"video": {
"name": "视频发送于2020-07-13_14_42.mp4",
"url": "https://yach-static.zhiyinlou.com/test/group/1594651255788/kjgicsmv0v/****.mp4"
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：video |
| name | String | 是 | 文件名称 |
| url | String | 是 | 调用完腾讯cos之后拿到的视频链接 |
| duration | Int | 否 | 正整数，表示视频时长，单位秒 |
| size | String | 否 | 视频大小，单位Kb |
| width | String | 否 | 视频宽度 |
| height | String | 否 | 视频高度 |
# 9、页面跳转消息（自动打开指定页面，url字段格式请参考：markdown消息的说明）：
{
"msgtype": "custom",
"custom": {
"type": "1",
"body": {
"url": "yach://yach.zhiyinlou.com/session/webview?url=encode编码后的链接"
}
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：custom |
| type | String | 是 | 类型（1:跳转链接） |
| body.url | String | 是 | 需要跳转的链接地址，请参考示例进行url_encode编码处理 |
# 10、灰色Tips消息：
{
"msgtype": "tips",
"tips": {
"text": "您已成功进行了评价 20：56"
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：tips |
| text | String | 是 | 提示文案 |
# 11、流式消息（仅聊天机器人支持）：
{
"msgtype":"stream",
"stream":{
"stream_id":"xxxxxxx1xxxx",
"quote_msg_id":"112121212121"
}
}
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：stream |
| stream_id | String | 是 | 消息流ID，知音楼开放平台会携带query参数以get方式请求聊天机器人回调域名，请确保可以正常接收处理，响应数据按照下面格式响应，响应格式为 Content-Type:text/event-stream |
| quote_msg_id | String | 否 | 引用回复的消息ID，要引用回复指定消息的话将机器人抄送消息的quote_msg_id传递过来 |
响应数据流单个 event 格式如下：
{
"msg_id":"xxxxxxx1xxxx",
"content":"知",
"is_finished": false
}
# 12、互动消息卡片
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| msgtype | String | 是 | 消息类型，此时固定为：sscard |
| last_msg | String | 是 | 会话列表消息展示内容 |
| sscard | list | 是 | UI 组件列表，组件定义参考互动消息卡片组件 |
# sscard仅支持的接口列表
1.发送助手消息
2.点对点普通消息
3.发送工作通知
4.点对点机器人消息
{
"msgtype": "sscard",
"sscard": [{
"type": "input",
"id": "title",
"title": {
"i18n": {
"zh_cn": "标题",
"en_us": "title"
}
},
"placeholder_title": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"length": 100,
"action_url": "https://xxxxx/test/sscard",
"extra": "",
"required": true,
"required_tips": {
"i18n": {
"zh_cn": "请输入标题",
"en_us": "please input title"
}
},
"prompt_tips": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"default_text": {
"i18n": {
"zh_cn": "新建日程",
"en_us": "新建日程"
}
}
}, {
"type": "date_picker",
"id": "start_time",
"title": {
"i18n": {
"zh_cn": "开始时间",
"en_us": "startTime"
}
},
"placeholder_title": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"action_url": "https://xxxxx/test/sscard",
"extra": "",
"required": true,
"required_tips": {
"i18n": {
"zh_cn": "请输入开始时间",
"en_us": "please input start time"
}
},
"prompt_tips": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"relation_tips": {
"i18n": {
"zh_cn": "开始时间必须早于结束时间",
"en_us": "start time must after end time"
}
},
"format": "yyyy-MM-dd HH:mm",
"default_time": 1712654165
}, {
"type": "date_picker",
"id": "end_time",
"title": {
"i18n": {
"zh_cn": "截止时间",
"en_us": "endTime"
}
},
"placeholder_title": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"action_url": "https://xxxxx/test/sscard",
"extra": "",
"required": true,
"required_tips": {
"i18n": {
"zh_cn": "请输入截止时间",
"en_us": "please input end time"
}
},
"prompt_tips": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"relation_type": "after",
"relation_id": "start_time",
"relation_tips": {
"i18n": {
"zh_cn": "结束时间必须晚于开始时间",
"en_us": "end time must before start time"
}
},
"format": "yyyy-MM-dd HH:mm",
"default_time": 1712655365
}, {
"type": "select_person",
"id": "select_person",
"title": {
"i18n": {
"zh_cn": "参会人",
"en_us": "attendee"
}
},
"placeholder_title": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"action_url": "https://xxxxx/test/sscard",
"extra": "",
"limit": 50,
"required": true,
"required_tips": {
"i18n": {
"zh_cn": "请选择参会人",
"en_us": "please select attendee"
}
},
"prompt_tips": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"default_person": "Yach111965"
}, {
"id": "conflict_text",
"type": "text",
"placeholder_title": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
},
"content": {
"type": "plain_text",
"i18n": {
"zh_cn": "111111",
"en_us": "2222"
},
"attributes_i18n": {
"zh_cn": null,
"en_us": null
}
}
}, {
"id": "confirm_button",
"type": "button",
"mutually_exclusive": 2,
"update_msg": false,
"content": [{
"id": "content_button",
"text": {
"i18n": {
"zh_cn": "确认并创建",
"en_us": "confirm and create"
}
},
"extra": "",
"text_color": "FFFFFF",
"border_color": "326FEF",
"background_color": "326FEF",
"icon_position": 0,
"url": "https://xxxxxx/test/sscard",
"action_type": "request",
"retrieve_values": ["title", "start_time", "end_time", "address", "select_person", "remark", "checkbox"],
"click_success": {
"i18n": {
"zh_cn": "",
"en_us": ""
}
}
}]
}],
"last_msg": "这里是会话消息列表展示内容"
}
