营销线索搜集场景对话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
}