开放能力
开发平台
行业应用
生态合作
开发与教学
资讯 社区 控制台
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术
AR与VR
数据智能
场景方案
部署方案
行业应用
智能教育
智能医疗
智能零售
智能工业
企业服务
智能政务
信息服务
智能园区

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

1. 基础接口

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

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

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

通过对话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"
        }
    }
}

示例中相关字段的说明可参考UNIT平台机器人对话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
}

示例中相关字段的说明可参考UNIT平台机器人对话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. 『对话接通』请求说明

事件 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进行调用时,建议在收到该应答后进行以下操作:

  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. 转人工配置

转人工配置

表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
}