营销线索搜集场景对话API文档
1. 基础接口
营销线索场景使用的对话API和UNIT平台机器人对话API保持一致,字段、调用方式等均相同,只是在此基础上做了进一步封装和定制化处理。建议开发者先了解机器人对话API接口。(营销线索场景仅支持使用机器人对话API接口2.0调用)
开发者可通过IM客户端接收用户输入,并通过API向机器人进行转发,得到机器人应答后在客户端向用户展示答复内容,从而达到搜集营销线索的目的,如图1所示。IM客户端需要开发者自行维护。
图1. 通过对话API接入的处理流程
2. 请求/应答示例
2.1 请求示例
{
"version":"2.0",
"service_id":"S22896",
"log_id":"UNITTEST_123456",
"session_id":"service-session-id-123456",
"request":{
"user_id":"1122334",
"query":"我的手机号是138xxxxxxxx",
"query_info":{
"asr_candidates":[],
"source":"KEYBOARD",
"type":"TEXT"
}
}
}
示例中相关字段的说明可参考机器人对话API接口。在本场景中,除了request.query
之外,需要额外关注的是session_id
与request.query.query_info.type
字段。
请求数据中,若session_id
为空,则为一段对话的首轮请求,机器人会在首轮应答中生成一个session_id
作为本段对话的标识。之后的各轮请求中将该session_id
原样填入请求中即可保持对话连续;反之若将session_id
清空,则会开始一段新的对话。
营销线索机器人支持以下2种对话发起方式:
- 通过『对话接通』事件请求来调起机器人(详见3.1),此时机器人会返回带有欢迎语的『启动服务』应答(详见4.1),开始执行一个完整的交互流程;
- 直接将用户输入的内容通过普通首轮请求的形式(session_id字段为空)发送给机器人,此情况下机器人会跳过欢迎语直接进入线索搜集。
开发者可根据自身情况决定使用哪种方式发起一段对话。
request.query.query_info.type
表示请求的类型,对于一般的客户端文字输入,取值为TEXT
;对于客户端上发生的特殊事件,如对话接通、静默超时、对话异常结束等,取值为EVENT
(详见第3节)。
2.2 应答示例
{
"result":{
"version":"2.0",
"timestamp":"2019-10-16 17:29:54.402",
"service_id":"S23037",
"log_id":"82cb6880-eff7-11e9-8507-e5fa34e17739",
"session_id":"service-session-id-123456",
"interaction_id":"interaction-82ecb576-eff7-11e9-84d5-fa163ed384d3",
"response_list":[
{
"status":0,
"msg":"ok",
"origin":"S23037",
"schema":{
"intent_confidence":0,
"slots":[
{
"word_type":"",
"confidence":100,
"name":"user_sex",
"length":1,
"original_word":"男",
"sub_slots":[],
"session_offset":0,
"begin":0,
"normalized_word":"男",
"merge_method":"update"
},
{
"word_type":"",
"confidence":100,
"name":"user_age",
"length":1,
"original_word":"19",
"sub_slots":[],
"session_offset":0,
"begin":0,
"normalized_word":"19",
"merge_method":"update"
}
],
"confidence":0,
"domain_confidence":0,
"slu_tags":[],
"intent":""
},
"action_list":[
{
"refine_detail":{
"option_list":[
{
"info":{
"name":"user_loc",
"text":"城市"
},
"option":"user_loc"
}
],
"interact":"ask",
"clarify_reason":"slot_absent"
},
"action_id":"user_loc_clarify",
"confidence":100,
"custom_reply":"",
"say":"您是在哪个城市呢?",
"type":"clarify"
}
],
"qu_res":{
"qu_res_chosen":"",
"candidates":[],
"sentiment_analysis":{
"pval":0,
"label":""
},
"lexical_analysis":[],
"raw_query":"",
"status":0,
"timestamp":0
}
}
],
"dialog_state":{
"contexts":{},
"skill_states":{}
}
},
"error_code":0
}
示例中相关字段的说明可参考机器人对话API接口。需要额外关注的有以下两点:
- 对于营销线索机器人,对话结果的产出不再以技能为单位,而是整个机器人产出一个结果,因此不再关注意图,因此应答中
response_list[].schema.intent
字段为空; - 搜集到的线索以词槽形式记录在
response_list[].schema.slots
中,开发者可以根据应答结果灵活选择记录时机(详见第4节)。
3. 事件型请求
营销线索场景中,除了上一节所展示的普通对话请求外,我们还需要用到一些事件型请求,客户端需要在适当的时机通过这些请求和服务端进行交互。事件型请求的request.type
字段值均为EVENT
,request.query
字段为一个内含event_name
字段的json字符串,用于标识事件名称。
3.1 对话接通
在每次对话刚接通(客户端检测到一个新的用户接入)时,需要首先向机器人发送一个『对话接通』事件请求,以告知机器人开启一次新的对话,机器人随之返回一个『启动服务』应答(见4.1)。在机器人测试窗口中,对话接通请求的发送是自动完成的,如图2所示,而在使用API进行调用时,需要客户端自行发送该请求,详细说明见表1。
图2. 『对话接通』交互流程示例
表1. 『对话接通』请求说明
事件 | event_name |
作用 |
---|---|---|
对话接通 | HELLO |
告知机器人有用户接入,开始一段对话 |
请求示例
{
"version":"2.0",
"service_id":"S22896",
"log_id":"UNITTEST_123456",
"session_id":"service-session-id-123456",
"request":{
"user_id":"1122334",
"query":"{\"event_name\":\"HELLO\"}",
"query_info":{
"asr_candidates":[],
"source":"KEYBOARD",
"type":"EVENT"
}
}
}
3.2 静默超时
在对话过程中,如果客户端检测到用户长时间没有说话,希望机器人主动发起针对性询问时,可以向机器人发送『静默超时』事件请求,机器人会根据高级设置中的静默超时设置(如图3所示)返回一个普通应答,以促使线索搜集继续进行。
图3. 『静默超时』应答设置
在机器人测试窗口中,静默超时请求的发送是自动完成的,如图4所示,而在使用API进行调用时,需要客户端进行超时检测和请求发送,超时时间设置可自行设定(体验窗口默认设定为60秒),详细说明见表2。
图4. 『静默超时』交互流程
表2. 『静默超时』请求说明
事件 | event_name |
作用 |
---|---|---|
静默超时 | SILENCE |
告知机器人有用户长时间无输入,产生相应应答处理 |
请求示例
{
"version":"2.0",
"service_id":"S22896",
"log_id":"UNITTEST_123456",
"session_id":"service-session-id-123456",
"request":{
"user_id":"1122334",
"query":"{\"event_name\":\"SILENCE\"}",
"query_info":{
"asr_candidates":[],
"source":"KEYBOARD",
"type":"EVENT"
}
}
}
3.3 异常结束
在对话过程中客户端如果检测到异常结束(如对话未完成情况下用户离开),可以通过发送『异常结束』事件请求告知机器人,机器人会直接给出一个『对话结束』应答(详见4.2),提示客户端结束对话并记录线索。机器人测试窗口不会发送此请求,开发者可通过对话API进行调用,详细说明见表3。
表3. 『异常结束』请求说明
事件 | event_name |
作用 |
---|---|---|
异常结束 | UNDESIRED_FINISH |
告知机器人对话在未完成情况下异常结束,直接触发结束处理 |
请求示例
{
"version":"2.0",
"service_id":"S22896",
"log_id":"UNITTEST_123456",
"session_id":"service-session-id-123456",
"request":{
"user_id":"1122334",
"query":"{\"event_name\":\"UNDESIRED_FINISH\"}",
"query_info":{
"asr_candidates":[],
"source":"KEYBOARD",
"type":"EVENT"
}
}
}
4. 事件型应答
在某些情况下,机器人会产生一些事件型应答以告知客户端对话进行到了特殊环节,需要客户端做一些针对性处理,如转人工、记录线索、结束对话等。事件型应答的action_list[].type
均为event
,并在action_list[].custom_reply
中包含一个以event_name
为key的json字符串,用于标识事件名称。
4.1 启动服务
对『对话接通』请求的应答,应答话术action_list[].say
为用户配置的欢迎语,action_list[].custom_reply
中的event_name
字段值为START_SERVE
,客户端获取到该应答时,不需做特殊处理,和普通请求一样展示应答话术即可,交互过程如图2所示。详细说明见表4。
表4. 『启动服务』应答说明
事件 | event_name |
作用 |
---|---|---|
启动服务 | START_SERVE |
对『对话接通』请求的应答 |
应答示例
{
"result":{
"version":"2.0",
"timestamp":"2019-10-16 17:29:54.402",
"service_id":"S23037",
"log_id":"82cb6880-eff7-11e9-8507-e5fa34e17739",
"session_id":"service-session-id-123456",
"interaction_id":"interaction-123456",
"response_list":[
{
"status":0,
"msg":"ok",
"origin":"S23037",
"schema":{
"intent_confidence":0,
"slots":[],
"confidence":0,
"domain_confidence":0,
"slu_tags":[],
"intent":""
},
"action_list":[
{
"refine_detail":{
"option_list":[],
"interact":"",
"clarify_reason":""
},
"action_id":"hello_satisfy",
"confidence":100,
"custom_reply":"{\"event_name\":\"START_SERVE\"}",
"say":"您好,很高兴为您服务",
"type":"event"
}
],
"qu_res":{
"qu_res_chosen":"",
"candidates":[],
"sentiment_analysis":{
"pval":0,
"label":""
},
"lexical_analysis":[],
"raw_query":"",
"status":0,
"timestamp":0
}
}
],
"dialog_state":{
"contexts":{},
"skill_states":{}
}
},
"error_code":0
}
4.2 对话结束
在需要结束对话时,无论是线索搜集完毕的正常结束或是其他异常结束,机器人都会产生『对话结束』应答,以提示客户端对话结束了。应答的话术是机器人配置中的结束语,如图5所示。
图5. 『对话结束』应答示例
开发者通过API进行调用时,建议在收到该应答后进行以下操作:
- 记录搜集到的线索
- 关闭对话窗口
开发者可根据自身情况决定要进行的操作。为保护隐私,机器人测试窗口只展示结束语及搜集到的线索,不进行记录。详细说明见表5。
表5. 『对话结束』应答说明
事件 | event_name |
作用 |
---|---|---|
对话结束 | FINISH_SERVE |
告知客户端对话结束了,可选择性进行记录线索、关闭对话等操作 |
应答示例
{
"result":{
"version":"2.0",
"timestamp":"2019-10-16 17:29:54.402",
"service_id":"S23037",
"log_id":"82cb6880-eff7-11e9-8507-e5fa34e17739",
"session_id":"service-session-id-123456",
"interaction_id":"interaction-123456",
"response_list":[
{
"status":0,
"msg":"ok",
"origin":"S23037",
"schema":{
"intent_confidence":0,
"slots":[
{
"word_type":"",
"confidence":100,
"name":"user_sex",
"length":1,
"original_word":"男",
"sub_slots":[],
"session_offset":0,
"begin":0,
"normalized_word":"男",
"merge_method":"update"
},
{
"word_type":"",
"confidence":100,
"name":"user_age",
"length":1,
"original_word":"19",
"sub_slots":[],
"session_offset":0,
"begin":0,
"normalized_word":"19",
"merge_method":"update"
}
],
"confidence":0,
"domain_confidence":0,
"slu_tags":[],
"intent":""
},
"action_list":[
{
"refine_detail":{
"option_list":[],
"interact":"",
"clarify_reason":""
},
"action_id":"bye_satisfy",
"confidence":100,
"custom_reply":"{\"event_name\":\"FINISH_SERVE\"}",
"say":"好的,您的信息已提交,稍后会有专业人员联系你,祝您生活愉快",
"type":"event"
}
],
"qu_res":{
"qu_res_chosen":"",
"candidates":[],
"sentiment_analysis":{
"pval":0,
"label":""
},
"lexical_analysis":[],
"raw_query":"",
"status":0,
"timestamp":0
}
}
],
"dialog_state":{
"contexts":{},
"skill_states":{}
}
},
"error_code":0
}
4.3 转人工
当用户输入命中了转人工配置(如图6所示)中的话术时,机器人会返回转人工应答,客户端可记录已搜集线索、转人工或做其他操作,详细说明见表6。
图6. 转人工配置
表6. 『转人工』应答说明
事件 | event_name |
作用 |
---|---|---|
转人工 | STAFF_SERVICE |
告知客户端,用户输入了转人工话术,可进行记录线索、转人工等操作 |
应答示例
{
"result":{
"version":"2.0",
"timestamp":"2019-10-16 17:29:54.402",
"service_id":"S23037",
"log_id":"82cb6880-eff7-11e9-8507-e5fa34e17739",
"session_id":"service-session-id-123456",
"interaction_id":"interaction-123456",
"response_list":[
{
"status":0,
"msg":"ok",
"origin":"S23037",
"schema":{
"intent_confidence":0,
"slots":[
{
"word_type":"",
"confidence":100,
"name":"user_age",
"length":1,
"original_word":"19",
"sub_slots":[],
"session_offset":0,
"begin":0,
"normalized_word":"19",
"merge_method":"update"
}
],
"confidence":0,
"domain_confidence":0,
"slu_tags":[],
"intent":""
},
"action_list":[
{
"refine_detail":{
"option_list":[],
"interact":"",
"clarify_reason":""
},
"action_id":"staff_service",
"confidence":100,
"custom_reply":"{\"event_name\":\"STAFF_SERVICE\"}",
"say":"好的,正在帮您转接人工客服",
"type":"event"
}
],
"qu_res":{
"qu_res_chosen":"",
"candidates":[],
"sentiment_analysis":{
"pval":0,
"label":""
},
"lexical_analysis":[],
"raw_query":"",
"status":0,
"timestamp":0
}
}
],
"dialog_state":{
"contexts":{},
"skill_states":{}
}
},
"error_code":0
}