资讯 社区 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

营销线索搜集场景对话API文档

1. 基础接口

营销线索场景使用的对话API和UNIT平台机器人对话API保持一致,字段、调用方式等均相同,只是在此基础上做了进一步封装和定制化处理。建议开发者先了解机器人对话API接口。(营销线索场景仅支持使用机器人对话API接口2.0调用)

开发者可通过IM客户端接收用户输入,并通过API向机器人进行转发,得到机器人应答后在客户端向用户展示答复内容,从而达到搜集营销线索的目的,如图1所示。IM客户端需要开发者自行维护。

图1. 通过对话API接入的处理流程

图片 0.png

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_idrequest.query.query_info.type字段。

请求数据中,若session_id为空,则为一段对话的首轮请求,机器人会在首轮应答中生成一个session_id作为本段对话的标识。之后的各轮请求中将该session_id原样填入请求中即可保持对话连续;反之若将session_id清空,则会开始一段新的对话。

营销线索机器人支持以下2种对话发起方式:

  1. 通过『对话接通』事件请求来调起机器人(详见3.1),此时机器人会返回带有欢迎语的『启动服务』应答(详见4.1),开始执行一个完整的交互流程;
  2. 直接将用户输入的内容通过普通首轮请求的形式(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接口。需要额外关注的有以下两点:

  1. 对于营销线索机器人,对话结果的产出不再以技能为单位,而是整个机器人产出一个结果,因此不再关注意图,因此应答中response_list[].schema.intent字段为空;
  2. 搜集到的线索以词槽形式记录在response_list[].schema.slots中,开发者可以根据应答结果灵活选择记录时机(详见第4节)。

3. 事件型请求

营销线索场景中,除了上一节所展示的普通对话请求外,我们还需要用到一些事件型请求,客户端需要在适当的时机通过这些请求和服务端进行交互。事件型请求的request.type字段值均为EVENTrequest.query字段为一个内含event_name字段的json字符串,用于标识事件名称。

3.1 对话接通

在每次对话刚接通(客户端检测到一个新的用户接入)时,需要首先向机器人发送一个『对话接通』事件请求,以告知机器人开启一次新的对话,机器人随之返回一个『启动服务』应答(见4.1)。在机器人测试窗口中,对话接通请求的发送是自动完成的,如图2所示,而在使用API进行调用时,需要客户端自行发送该请求,详细说明见表1。

图2. 『对话接通』交互流程示例

图片 1.png

表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. 『静默超时』应答设置

图片 2.png

在机器人测试窗口中,静默超时请求的发送是自动完成的,如图4所示,而在使用API进行调用时,需要客户端进行超时检测和请求发送,超时时间设置可自行设定(体验窗口默认设定为60秒),详细说明见表2。

图4. 『静默超时』交互流程

图片 3.png

表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. 『对话结束』应答示例

图片 4.png

开发者通过API进行调用时,建议在收到该应答后进行以下操作:

  1. 记录搜集到的线索
  2. 关闭对话窗口

开发者可根据自身情况决定要进行的操作。为保护隐私,机器人测试窗口只展示结束语及搜集到的线索,不进行记录。详细说明见表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. 转人工配置

图片 5.png

表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
}
上一篇
资源API
下一篇
接入微信公众号