bot_platform_201609

Size: px

Start display at page:

Download "bot_platform_201609"

瑕毖味疏
5 years ago
Views:

1 bot.qq.com 机器器人开放平台开发者文档 ( 预览版 )

2 一概述你可以通过机器器人开放平台提供的工具和接口快速构建一个机器器人 1 申请加入前往 bot.qq.com 找到申请入口填写企业个人资料料选择所属领域并等待审核审核通过后可以获得对应领域的接入指引 2 创建机器器人在 bot.qq.com 提供的工具中配置你需要识别的意图和实体你可以选择已有意图和实体也可以创建新的意图并上传对应的实体 2 发现机器器人用户在腾讯应用宝中发现一款机器器人并与机器器人展开对话 3 开展对话配置完成意图和实体后当用户向你发送消息时机器器人平台会为你识别用户表达的含义你可以通过发送消息和接收消息接口与用户进行行一次对话为他提供服务机器器人平台提供多种消息格式可以发送简单的文本和图片也可以使用消息模版来自定义消息气泡使用消息模版你可以在一条消息中呈现图片文本和多个按钮

二语义识别语义理理解覆盖多个垂直领域的场景, 开发者无需了了解语义理理解相关技术, 只需要根据自身产品功能选择领域, 即可获取所需识别的意图和实体 1 协议描述语言协议采用结构化的描述语言 JSON 进行行表示, 采用 utf8 进行行编码此处简述 JSON 的几个核心概念 : 属性名 / 属性值值 (value) 可以是双引号括起来的字符串串 (string)

3 二语义识别语义理理解覆盖多个垂直领域的场景, 开发者无需了了解语义理理解相关技术, 只需要根据自身产品功能选择领域, 即可获取所需识别的意图和实体 1 协议描述语言协议采用结构化的描述语言 JSON 进行行表示, 采用 utf8 进行行编码此处简述 JSON 的几个核心概念 : 属性名 / 属性值值 (value) 可以是双引号括起来的字符串串 (string) 数值 (number) true false null 对象 (object) 或者数组 (array) 这些结构可以嵌套数组数组是值 (value) 的有序集合一个数组以 [ ( 左中括号 ) 开始, ] ( 右中括号 ) 结束值之间使用, ( 逗号 ) 分隔对象对象是一个无序的名称 / 值对集合一个对象以 ( 左括号 ) 开始, ( 右括号 ) 结束每个名称后跟一个 : ( 冒号 ); 名称 / 值对之间使用, ( 逗号 ) 分隔 2 语义识别领域 (domain) 领域是指某一类型的数据或者服务, 比如 : 应用新闻视频音乐电影飞机票图片处理理意图 (intent) 意图是指对于领域数据的操作, 比如电影领域中, 有 : 查询影片查询影院实体 (entities) 实体是指对于意图中包含的参与, 比如查询影院意图中, 包含 : 影院名城市商圈语义表示结构如下 :

4 每个领域的语义表示协议均包含以下内容 : 字段名称字段类型是否必选字段说明 domain string 是领域 intent string 是意图 entities string 是实体语义理理解示例例 : 查询深圳市海海岸城的电影院 domain : movie, intent : search_ cinema, entities : city : 深圳, regions : 海海岸城

5 3 通用协议基本符合类型 (basic) 基本复合类型包含 raw 和 norm 两个字段,raw 代表用户 query 中的原始表述,norm 表示归一化之后的标准表述日期时间 (datatime) 日期时间类型定义了了一种结构, 可以描述时间点和时间段两种类型, 根据 type 字段的取值不不同 type 类型时间点 / 时间区间字段说明 before 时间区间某个时间点之前 after 时间区间某个时间点之后 equal 时间点某个时间点 about 时间区间某个时间点左右 interval 时间区间两个时间点之间时间协议字段名称字段类型字段说明 type string 上表中的五种类型 raw string query 中的原始内容 norm array 归一化后的时间描述格式为 :yyyy-mm-dd hh:mm:ss 在时间段的表述中, 有早上, 下午等时间段表述我们定义这些时间段的始末时间为 : 时间段表示开始结束时间点早晨, 早上, 清晨 06:00 08:00 07:00 上午 08:00 12:00 10:00 中午 11:00 13:00 12:00 下午, 午后 12:00 18:00 15:00 晚上, 傍晚 18:00 24:00 21:00 清晨 00:00 05:00 03:00 半夜深夜午夜 23:00 01:00 00:00

6 示例例 : 明天下午两点前 "time": [ "norm": [ " :00:00 ], ] "raw": " 明天下午两点前 ", "type": before"

7 地点 (location) 地点类型定义了了一种结构, 可以描述多种地点类型, 根据 type 字段的取值不不同 type 类型 loc_country loc_province loc_city 字段说明国家省市 loc_town 县 ( 区 ) loc_poi 详细地址定义表达地点的数据结构字段名称字段类型字段说明 type string 上表中的五种类型 country string 国家 province string 省全称, 如 : 广东省 province_simple string 省简称, 如 : 广东 city string 市全称, 如 : 北北京市 city_simple string 市简称, 如 : 北北京 town string 县 ( 区 ) 全称, 如 : 海海淀区 town_simple string 县 ( 区 ) 简称, 如 : 海海淀 longitude double 经度 ( 以腾讯地图为准 ) latitude double 纬度 ( 以腾讯地图为准 ) poi string poi 描述 location_poi string 详细地址

8 示例例 : 深圳腾讯大厦 "location": "type": "loc_poi", "province": " 广东省 ", "province_simple": " 广东 ", "city": " 深圳市 ", "city_simple": " 深圳 ", "town": " 南山区 ", "town_simple": " 南山 ", "longitude": ", "latitude": " ", "poi": " 深南大道号 ", "loc_ori": " 广东省深圳市南山区深南大道号 "

9 数字 (number) 定义 type 类型 type 类型数字 / 数字区间字段说明 less 数字区间小于某个数字 more 数字区间大于某个数字 equal 数字等于某个数字 about 数字区间某个数字左右 interval 数字区间两个数字之间数字协议字段名称字段类型字段说明 type string 同时间协议中的五种类型 raw string query 中的原始内容 norm array 归一化后的时间描述示例例 : 不不到一百元 "norm":[ 100 ], "raw":" 不不到一百元 ", "type":"less"

10 4 领域示例例下面为你提供一些领域的示例例, 你可以选择已有意图和要素, 也可以利利用机器器人平台提供的在线工具, 创建意图和要素分类领域请求示例例资讯 news 查询资讯, 如 : 里里约奥运会视频 video 查询视频, 如 : 里里约奥运会音乐 music 播发音乐, 如 : 周杰伦内容图片 picture 查询图片, 如 : 搞笑小说 novel 查询小说, 如 : 微微一笑很倾城菜谱 cookbook 查询菜谱, 如 : 宫保鸡丁怎么做百科 wiki 查询百科知识, 如 : 周杰伦是谁餐饮 restaurant 查询餐厅, 如 : 附近的餐厅酒店 hotel 查询酒店, 如 : 深圳的酒店生活服务电影票 movie 查询影院, 如 : 附近的电影院机票 flight 查询机票, 如 : 深圳到北北京的机票火车票 train 查询机票, 如 : 深圳到北北京的火车票工具天气 weather 查询天气, 如 : 今天天气如何提醒 remind 设置提醒, 如 : 明天八点开会

11 4.1 内容类资讯领域 (domin) news 意图 (intent) search 查询新闻字段名称字段类型字段说明示例例实体 (entities) keyword string 关键词里里约奥运会 category string 新闻类别体育示例例 : 里里约奥运会的新闻 "domain": "news", "intent": "search", "entities": "keyword": 里里约奥运会 ", "category": " 体育 "

12 4.1.2 视频领域 (domin) video 意图 (intent) search 查询视频字段名称字段类型字段说明示例例 title string 视频名 / 关键词暴暴走漫画 category string 视频类别搞笑 actor string 主演 / 参演王尼玛实体 (entities) director string 导演 / 主持人王尼玛 country string 地区美国 season number 季第一季 episode number 集第一集 sort int 排序规则 0, 好评 ( 默认 ); 1, 热门 ;2, 经典 ; 示例例 : 来一部成龙演的经典电影 "domain": "video", "intent": "search", "entities": "title": "", "category": "", "actor": 成龙 ", "director": "", "country": "", "season": "", "episode": "", "sort": 2

13 4.1.3 音乐领域 (domin) music 意图 (intent) search 查询音乐字段名称字段类型字段说明示例例 song string 歌曲名七里里香 artist string 歌手周杰伦 album string 专辑简单爱实体 (entities) chart string 排行行榜歌曲热榜 genre string 曲风流行行 language string 语言中文 scene string 场景运动 mood string 情绪开心 artist_category string 歌手分类港台男歌手示例例 : 我要听欧美说唱 "domain": "music", "intent": "search", "entities": "song": "", "artist": "", "album": "", "chart": "", "genre": 说唱 ", "language": "", "scene": "", "mood": ", "artist_category": " 欧美 "

14 4.1.4 图片领域 (domin) picture 意图 (intent) search 查找图片字段名称字段类型字段说明示例例实体 (entities) keyword string 关键词狗 category string 新闻类别搞笑示例例 : 可爱的小狗 "domain": "picture", "intent": "search", "entities": "keyword": 狗, "category": " 可爱 "

15 4.1.5 小说领域 (domin) novel 意图 (intent) search 查找小说字段名称字段类型字段说明示例例 name string 小说名微微一笑实体 (entities) genre string 小说类型武侠 sense string 阅读场景睡前读物 author string 小说作者三叔 chapter string 小说章节 1 示例例 : 阅读微微一笑很倾城 "domain": "novel", "intent": "search", "entities": "name": " 微微一笑很倾城 ", "genre": 青春 ", "sense": ", "author": 顾漫 ", "chapter": ""

16 4.1.6 菜谱领域 (domin) cookbook 意图 (intent) search 查找菜谱字段名称字段类型字段说明示例例 name string 菜名鸡蛋西红柿 material string 食材鸡蛋 sense string 菜谱场景中秋节实体 (entities) category string 菜系江浙菜 tool string 工具微波炉 taste string 口味甜 action string 做法炒 crowd string 适合人群儿童示例例 : 糖醋里里脊怎么做 "domain": "novel", "intent": "search", "entities": "name": 糖醋里里脊 ", "material": [ " 糖 ", " 醋 ", 里里脊 " ], "sense": "", "category": "", "tool": "", "taste": [ ], 甜 ", " 酸 " "action": 炒 ", "crowd": ""

17 4.1.7 百科领域 (domin) wiki 意图 (intent) search 查询实体 (entities) 字段名称字段类型字段说明示例例 keyword string 关键词刘德华示例例 : 刘德华是谁 "domain": "wiki", "intent": "search", "entities": "keyword": 刘德华 "

18 4.2 生活服务类餐厅领域 (domin) restaurant 意图 (intent) search 查找餐厅字段名称字段类型字段说明示例例 name string 餐厅名麦当劳 location location 地点深圳市海海岸城实体 (entities) category string 菜系粤菜 dish string 推荐菜烤鸭 tag string 餐厅特色情侣约会 price string 人均价格 100 示例例 : 推荐附近的的粤菜 "domain": "restaurant", "intent": "search", "entities": "name": "", "location": "type": "loc_poi", "province": " 广东省 ", "province_simple": " 广东 ", "city": " 深圳市 ", "city_simple": " 深圳 ", "town": " 南山区 ", "town_simple": " 南山 ", "longitude": ", "latitude": " ", "poi": " 深南大道号 ", "loc_ori": " 广东省深圳市南山区深南大道号 " "dish": " 粤菜 ", "tag": "", "price": ""

19 4.2.2 酒店领域 (domin) hotel 意图 (intent) search 查找酒店字段名称字段类型字段说明示例例 name string 酒店名丽思卡尔顿 location location 地点深圳福田区 brand string 酒店品牌希尔顿实体 (entities) datatime datatime 入住时间 , price number 价格 star int 酒店星级 1, 一星 ;2, 二星 ( 经济 );3, 三星 ( 舒适 );4, 四星 ( 高档 );5, 五星 ( 奢华 ) service string 特色服务 wifi

20 示例例 : 深圳市腾讯大厦附近的经济型酒店 "domain": "restaurant", "intent": "search", "entities": "name": "", "location": "type": "loc_poi", "province": " 广东省 ", "province_simple": " 广东 ", "city": " 深圳市 ", "city_simple": " 深圳 ", "town": " 南山区 ", "town_simple": " 南山 ", "longitude": ", "latitude": " ", "poi": " 深南大道号 ", "loc_ori": " 广东省深圳市南山区深南大道号 ", "brand": "", "datatime": "", "price": "", "star": 2, "service": ""

21 4.2.3 电影票领域 (domin) 意图 (intent) movie search_movie search_cinema 查找影票查找电影院字段名称字段类型字段说明示例例 name string 影片名谍影重重 movie_type string 影片类型动作 director string 导演杜琪峰实体 (entities) actor string 演员范冰冰 release_type string 影片类型在映即将上映 datatime datatime 观影时间 cinema string 影院名万达影院 location location 地点深圳市保安全 service string 影院特色 IMAX

22 示例例 : 今天八点深圳市保利利剧院的谍影重重 "domain": "movie", "intent": "search_movie", "entities": "name": " 谍影重重 ", "movie_type": "", "director": "", "actor": "", "release_type": " 在映 ", "datatime": "norm": [ " :00:00" ], "type": "equal", "raw": " 今天八点 ", "cinema": " 保利利剧院 ", "location": "type": "loc_poi", "province": " 广东省 ", "province_simple": " 广东 ", "city": " 深圳市 ", "city_simple": " 深圳 ", "town": " 南山区 ", "town_simple": " 南山 ", "poi": " 后海海滨路路 3013", "loc_ori": " 广东省深圳市南山区后海海滨路路 3013", "service": ""

23 4.2.4 机票领域 (domin) 意图 (intent) flight search_flight_ticket search_flight_info 查询飞机票查询航班信息字段名称字段类型字段说明示例例 datatime datatime 起飞时间 from location 出发地北北京 to location 目的地深圳 number string 航班号 ZH5016 实体 (entities) airtype string 机型 A380 company string 航空公司南航 transfer int 是否中转 0, 否 ;1, 是 ; round int 是否往返 0, 否 ;1, 是 ; grade int 舱位等级 sort int 排序规则 1, 经济舱 ;2, 商务舱 ;3, 头等舱 ; 1, 最早起飞 ;2, 价格最低 ;

24 示例例 : 明天北北京到深圳的头等舱机票 "domain": "flight", "intent": "search_flight_ticket", "entities": "datatime": "norm": [ " :00:00", " :59:59" ], "type": "interval", "raw": " 明天 ", "from": "type": "loc_city", "province": "", "province_simple": "", "city": " 北北京市 ", "city_simple": " 北北京 ", "town": "", "town_simple": "", "poi": "", "loc_ori": "", "to": "type": "loc_city", "province": "", "province_simple": "", "city": " 深圳市 ", "city_simple": " 深圳 ", "town": "", "town_simple": "", "poi": "", "loc_ori": "", "number": "", "airtype": "", "company": "", "transfer": 0, "round": 0, "grade": 3, "sort": 1

25 4.2.5 火车票领域 (domin) 意图 (intent) train search_train_ticket search_train_info 查询火车票查询车次信息字段名称字段类型字段说明示例例 datatime datatime 出发时间 from location 出发地北北京 from_station string 出发火车站北北京西站 to location 目的地深圳 to_station string 到达火车站深圳北北站实体 (entities) type int 火车类型 grade int 座位等级 sort int 排序规则 1, 高铁 / 城际 ;2, 动车 ;3, 直达 ;4, 特快 ;5, 快速 ;6, 其他 ; 0, 全部 ;1, 商务座 ;2, 特等座 ;3, 一等座 ;4, 二等座 ;5, 高级软卧 ; 6, 软卧 ;7, 硬卧 ; 8, 软座 ;9, 硬座 ; 10, 无座 ;11, 其他 1, 最早发车 ;2, 价格最低 ;

26 示例例 : 明天北北京到深圳的高铁 "domain": "train", "intent": "search_train_ticket", "entities": "datatime": "norm": [ " :00:00", " :59:59" ], "type": "interval", "raw": " 明天 ", "from": "type": "loc_city", "province": "", "province_simple": "", "city": " 北北京市 ", "city_simple": " 北北京 ", "town": "", "town_simple": "", "poi": "", "loc_ori": "", "from_station": "", "to": "type": "loc_city", "province": "", "province_simple": "", "city": " 深圳市 ", "city_simple": " 深圳 ", "town": "", "town_simple": "", "poi": "", "loc_ori": "", "to_station": "", "type": 1, "grade": 0, "sort": 0

27 4.3 工具类天气领域 (domin) weather 意图 (intent) search_weather search_temperature search_quality search_rainsnow search_wind search_ humidity 查询天气综合信息查询温度查询空气质量量查询雨雪信息查询风力力信息查询湿度字段名称字段类型字段说明示例例实体 (entities) datatime datatime 出发时间示例例 : 明天深圳的天气如何 location location 地点深圳市南山区 "domain": "weather", "intent": "search_weather", "entities": "datatime": "norm": [ " :00:00", " :59:59" ], "type": "interval", "raw": " 明天 ", "location": "type": "loc_city", "province": "", "province_simple": "", "city": " 深圳市 ", "city_simple": " 深圳 ", "town": "", "town_simple": "", "poi": "", "loc_ori": ""

28 4.3.2 提醒领域 (domin) alarm 意图 (intent) add_alarm search_alarm delete_alarm 创建提醒查询提醒删除提醒字段名称字段类型字段说明示例例实体 (entities) datatime datatime 时间 event string 事件开会示例例 : 提醒我明天八点开会 "domain": "alarm", "intent": "add_alarm", "entities": "datatime": "norm": [ " :00:00" ], "type": "equal", "raw": " 明天八点去开会 ", "event": 开会

29 三消息管理理接口形式请求方式 :POST aes(botkey,req) 接口数据 req: "head": "callbackpara": "callback01", "nonce": , "timestamp": , "body": [ "uid": "xx", "filed1": "filed1", "filed2": "filed2", "uid": "xx", "filed1": "filed1", "filed2": "filed2" ] rsp: "head": "callbackpara": "callback01", "ret": 0, "body": "data": [] 注 : 其中 body 根据具体协议而定, 可以是数组, 也可以是具体对象 req,rsp 不不为明文传输, 通过 AES 加密后以 post 数据传输

30 参数说明字段名称字段类型字段说明 callback_para string 回传参数, 请求方设置的值, 响应包返回时原内容返回 nonce int 随机数, 短时间内 ( 暂定 1 分钟 ) 不不重复 timestamp int 时间戳, 即 Unix 时间戳秒数返回码错误代码描述 0 成功 < 0 系统相关错误验证相关错误业务相关错误 AES 加解密密钥长度 :32 字节密钥来源 : 官网上申请接入系统自动分配 32 字节长度的 botkey(cp 需要谨慎保存避免泄露露 )

31 1 接收消息当用户向机器器人发送消息时, 机器器人平台将用户发送的原文语义识别后的归一化内容,POST 消息到开发者填写的 URL 1.1 文本示例例 : 明天深圳的天气 "head": "callbackpara": "callback01", "nonce": , "timestamp": , "body": "raw": " 明天深圳的天气 ", "domain": "weather", "intent": "search_weather", "entities": "datatime": "norm": [ " :00:00", " :59:59" ], "type": "interval", "raw": " 明天 ", "location": "type": "loc_city", "province": "", "province_simple": "", "city": " 深圳市 ", "city_simple": " 深圳 ", "town": "", "town_simple": "", "poi": "", "loc_ori": ""

32 参数说明字段名称字段类型字段说明 raw string 原文 domain string 领域 intent string 意图 entities string 要素 datatime datatime 时间 location location 地点

33 2 回复消息机器器人根据接到到的意图和要素, 选择响应格式回复用户 2.1 文本消息示例例 : 明天深圳 31 度 "head": "callbackpara": "callback01", "ret": 0, "body": [ "type": 0, ] "content": " 明天深圳 31 度 " 参数说明字段名称字段类型字段说明 type int 0, 文本消息 content string 文本内容

34 2.2 图片消息机器器人需要用到的所有图片, 必须先上传图片获取可用的 URL 上传图片获取 URL "head": "callbackpara": "callback01", "nonce": , "timestamp": , "body": "pic_url": " 返回说明 "head": "callbackpara": "callback01", "ret": 0, "body": "pic_url": " 图片消息示例例 : "head": "callbackpara": "callback01", "ret": 0, "body": [ "type": 1, "pic_url": " ]

35 参数说明字段名称字段类型字段说明 type int 1, 图片消息 pic_url string 图片URL

36 2.3 图文模版示例例 : "head": "callbackpara": "callback01", "ret": 0, "body": [ "type": 2, "pic_url": " ] "title": 谍影重重 5, "content": 影片讲述在后斯诺登时代, 伯恩重出江湖, 调查身份抗击反派的故事参数说明字段名称字段类型字段说明 type int 2, 图文消息 pic_url string 图片URL title string 标题 content string 描述

37 2.4 带按钮的图文模版示例例 : "head": "callbackpara": "callback01", "ret": 0, "body": [ "type": 3, "pic_url": " ] "title": 谍影重重 5, "content": 影片讲述在后斯诺登时代, 伯恩重出江湖, 调查身份抗击反派的故事 "postback": buy_ticket" 参数说明字段名称字段类型字段说明 type int 3, 带按钮的图文消息 pic_url string 图片URL title string 标题 content string 描述 postback string 自定义返回内容, 当用户点击按钮后触发, 以文本格式返回给开发者

38 2.5 订单卡片订单卡片示例例 : "head": "callbackpara": "callback01", "ret": 0, "body": [ "type": 200, "order_id": 1, "order_price": 100, "order_status": 1, ] "order_comment": " 不不支持退款 " 参数说明字段名称字段类型字段说明 type int 100, 订单卡片 order_id int 订单编号 order_price int 订单价格 order_status int 订单状态 order_comment string 订单备注

39 2.5.2 更更新订单状态示例例 : "head": "callbackpara": "callback01", "ret": 0, "body": [ "type": 201, "order_id": 1, "order_price": 100, "order_status": 2, ] "order_comment": " 不不支持退款 " 参数说明字段名称字段类型字段说明 type int 100, 订单卡片 order_id int 订单编号 order_price int 订单价格 order_status int 订单状态 order_comment string 订单备注

40 2.5.2 查询订单状态请求示例例 : "head": "callbackpara": "callback01", "nonce": , "timestamp": , "body": "order_id": 1 响应示例例 : "head": "callbackpara": "callback01", "ret": 0, "body": "order_status": 1

41 2.6 支付卡片示例例 : "head": "callbackpara": "callback01", "ret": 0, "body": [ "type": 200, "order_price": 100 "order_status": 1, ] 参数说明字段名称字段类型字段说明 type int 200, 支付卡片 order_id int 订单编号 order_price int 订单价格

42 2.7 快捷回复快捷输入为用户提供快捷选项, 可以与其他消息格式结合使用示例例 : "head": "callbackpara": "callback01", "ret": 0, "body": [... ] "quick_reply": 换一个, 加入购物车 " 参数说明字段名称字段类型字段说明 quick_reply string 快捷回复选项, 多个选项间以逗号分隔

43 3 群发消息你可以通过 bot.qq.com 中的在线工具向用户群发消息机器器人账号可以每天群发一条消息, 消息可以发送给关注该机器器人的用户 ( 机器器人存在于用户的机器器人列列表, 既可被当作关注 ) 可选择消息类型包括 : 纯文本单条图文多条图文 ( 最多三条 )

<4D6963726F736F667420576F7264202D20D6D0CEC4B7A88C57B454CABF8C57CEBBD593CEC4D28EB9A0>

<4D6963726F736F667420576F7264202D20D6D0CEC4B7A88C57B454CABF8C57CEBBD593CEC4D28EB9A0> 澳門大學法學院中文法學碩士學位論文規範一適用範圍 ( 一 ) 中文法學碩士學位論文是中文法學碩士學位研究生在指導教師的指導下獨立完成的, 合乎嚴格的寫作規範並標誌著獲得法學碩士學位的一篇書面作品中文法學碩士研究生