Skip to content

Latest commit

 

History

History
925 lines (732 loc) · 25.9 KB

TELROBOT.md

File metadata and controls

925 lines (732 loc) · 25.9 KB

讯飞开放平台AI能力-客服中间件

简介

AI客服平台能力中间件接口服务,支撑用户的个性化业务需求。按照呼叫方向, 分为呼入模式和呼出(外呼)模式。

呼入模式

呼入对接模式是指开发者在需要时主动发起呼叫,由AI电话机器人接听呼入的电话并进行人机交互。

标准交互场景

1、开发者利用自有CTI 系统接通客户电话;

2、开发者 CTI 系统向AI电话机器人发起 SIP 呼叫,用于桥接机器人话路和客户话路;

3、AI电话机器人接听 SIP 来电;如果话术需要上下文动态数据,则由机器人通过 Rest 请求从开发者的业务系统中拉取(详见呼入话术上下文动态数据获取部分);

4、开发者 CTI 系统将机器人话路和客户话路进行桥接;

5、客户与AI进行人机对话交互;

6、对话结束后,根据开发者预先设置的 URL(详见结果数据推送部分),向开发者的业务系统推送交互结果数据。

呼出(外呼)模式

呼出(外呼)模式是指开发者使用AI电话机器人主动呼叫客户电话,并进行人机交互的模式。讯飞开放平台不提供外呼中继线路,只提供外呼调度控制能力,开发者需要自行从运营商(或线路商) 申请可外呼的中继线路,然后将外呼中继线路对接到讯飞开放平台,为机器人提供外呼话路通道。

标准交互场景

1、开发者的业务系统调用AI电话机器人能力中间件 API 提交客户号码和数据;

2、AI电话机器人通过开发者的外呼中继线路并发呼叫客户电话;

3、客户接听后与AI电话机器人进行人机对话交互;

4、对话结束后,AI电话机器人根据开发者预先设置的 URL(详见结果数据推送部分),向开发者的业务系统推送交互结果数据。


注:这里的“客户”是指开发者(企业)的客户,是通过电话与AI电话机器人交互的人。

接口协议说明

请求方向:由应用方主动请求开放平台

请求方式:HTTPS POST

字符编码:UTF-8

请求头:Content-Type: application/json;charset=UTF-8

返回格式:json

返回json对象说明

开放平台的所有json响应消息采用标准对象定义,全部具有code、message和result三个属性。

名称 类型 说明
code int 返回码。0:成功,其它值表示失败,具体参考“附录:返回码参照”
message string 返回码描述
result object 返回结果集。

接口能力调用

获取token

功能:获取授权令牌。请求本接口之外的其它接口时,必须在接口url中通过token参数携带令牌。令牌有效期默认1小时,需要在过期前重新获取。

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/oauth/v1/token

请求参数说明

名称 必填 类型 说明
app_key string 应用的app_key,长度为48字节,详细内容可在相应的应用控制台 ==> 已开通服务中查看
app_secret string 应用的app_secret,长度为44字节,详细内容可在相应的应用控制台 ==> 已开通服务中查看
请求示例
POST https://callapi.xfyun.cn/v1/service/v1/aicall/oauth/v1/token HTTP/1.1
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache

{
   "app_key": "ODM1ZTk4ODAtYTMyZC00ZjBiLTkzMDQtY2VjNWU0ZDUyZWQ5",
   "app_secret": "MTM5NUM3NjlGQ0M2REUwN0FBREE3QjUxMkU1Qzg5NUQ="
}

响应示例

HTTP/1.1 200 OK
Content-Length:98
Date:Fri, 10 Aug 2018 06:58:01 GMT

{
    "code": 0,  
    "message": "ok",  
    "result": {
       "token": "08236d0aeeee4d5b566db5f4adc41a63",
       "time_expire": 3600
    }      
}

result返回结果集说明

名称 必填 类型 说明 备注
token string 令牌
time_expire long 有效期 单位:秒。默认3600。

查询配置

功能:查询企业下的各项资源及配置信息

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/config/v1/query?token=08236d0aeeee4d5b566db5f4adc41a63

请求参数说明

名称 必填 类型 说明
type int 配置项分类。1:话术,2:线路,3:接口,4:发音人,0:全部(默认)。

请求示例

{
   "type": 0
}

响应示例

{
    "code": 0,  
    "message": "ok",  
    "result": {
       "lines": [
           {
               "line_num": "055169101407",
               "concurrents": 10,
               "time_work": ["09:00:00-12:00:00", "13:00:00-17:59:59"],
               "status": 1,
               "time_apply": 1527321492000,
               "time_expire": 2592000
           },
           {
               "line_num": "055169101408",
               "concurrents": 100,
               "time_work": ["08:00:00-20:00:00"],
               "status": 0,
               "time_apply": 1527321492000,
               "time_expire": 2592000
           }
       ],
       "robots": [
           {
               "robot_id": "111111",
               "robot_name": "金融外呼",
               "call_column":["客户手机号码","姓名","性别"],
               "status": 4,
               "type": 1,
               "deleted": 0,
               "time_create": 1527321492000,
               "time_update": 1527325092000
           }
       ],
       "urls": [
           {
               "url": "http://your-service.url/receiveCallRecord",
               "url_module": "receiveCallRecord"
           }
       ],
       "voices": [
           {
               "voice_code": "60020",
               "voice_name": "春春"
           }
       ]
    }  
    
}  

result返回结果集说明

名称 类型 说明 备注
lines object[] 线路
line_num string 号码
concurrents int 并发数 此线路的最大并发数
time_work string[] 工作时段 电话机器人工作时段
status int 状态 0:空闲,即该线路上没有正在执行的任务 1:任务占用中,即该线路上当前有任务正在执行。
time_apply long 申请时间 线路的对接时间。数值:毫秒时间戳
time_expire long 有效期 线路的有效期。单位:秒。-1:永久有效。
robots object[] 话术
robot_id string 话术编号
robot_name string 话术名称
call_column string[] 外呼数据列模板 第一列必须是客户手机号,其他列是话术动态信息。
status int 话术状态 当前已创建的话术库状态。 1:审核中,2:未通过,3:待发布,4:已发布。
type int 话术类型 1:普通话术,2:动态话术。
其中动态话术是指包含多个话术组,能够实现动态跳转,动态话术适用于业务模式比较大流程比较复杂的情况,划分成多个子流程后,一方面管理维护容易,另外一方面可以复用。详细请登录后台管理平台话术库中体验。
deleted int 删除标记 0:未删除,1:已删除。
time_create long 话术创建时间 毫秒时间戳
time_update long 话术更新时间 毫秒时间戳
urls object[] 接口配置
url string 接口URL 应用方提供给平台回调的接口服务url地址,用于结果数据推送和呼入话术上下文动态数据获取(可选)。
url_module string 接口模块 详见结果数据推送呼入话术上下文动态数据获取 中的接口模块名称。
voices object[] 发音人 见【常用发音人清单】
voice_code string 发音人编码 见【常用发音人清单】
voice_name string 发音人名称 见【常用发音人清单】

常用发音人清单

voice_name voice_code 性别
春春 65580 女声
晓诗 62140 女声
晓燕 60020 女声
晓峰 60030 男声
小陈 65660 男声
楠楠 60130 女声
晓医 65600 女声

具体发音效果建议通过后台管理平台话术编辑的话术预览进行体验。


直接外呼

功能:面向便捷外呼业务场景,提交号码数据同时指定线路和机器人话术,直接发起外呼。直接外呼的号码数据将被提交到应用默认对应的长期任务下。如果号码数据中存在不合规记录(例如敏感号码、非手机号等)将会整批失败。

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/outbound/v1/task/callout?token=08236d0aeeee4d5b566db5f4adc41a63

请求参数说明

名称 必填 类型 说明 备注
robot_id string 话术编号
line_num string 线路号码
call_column string[] 外呼数据列
call_list string[][] 外呼数据行 单次上限50条
voice_code string 发音人编码

请求示例

{
    "line_num":"69101338",
    "robot_id":"719",
    "call_column":["客户手机号码","姓名"],
    "call_list":[["13000000001","张先生"],["13000000002","王女士"]],
    "voice_code":"60030"
}

响应示例

{
    "code": 0,  
    "message": "ok",  
    "result": {
        "total": 2,
        "task_data_ids": [130,131]
    }     
}

result返回结果集说明

名称 类型 说明
total int 号码总数
task_data_ids long[] 外呼数据行对应的任务数据编号,用于结果推送数据关联。

创建外呼任务

功能:面向需要灵活管控的业务场景。可以按照不同的业务维度创建多组任务、分批多次向指定任务提交号码数据,可以对外呼任务进行启动、暂停、删除等控制操作。

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/outbound/v1/task/create?token=08236d0aeeee4d5b566db5f4adc41a63

请求参数说明

名称 必填 类型 说明 备注
task_name string 任务名称
line_num string 线路号码 如果是多个,分号分隔
robot_id string 话术id
recall_count int 重试外呼次数 最大3次,默认0
time_recall_wait long 重试等待时间 单位秒
time_range string[] 外呼时间段
time_begin long 任务开始时间 毫秒时间戳
time_end long 任务结束时间 毫秒时间戳
voice_code string 发音人编码

请求示例

{
   "task_name": "测试外呼",
   "line_num": "055169101407",
   "robot_id": "11",
   "recall_count": 1,
   "time_recall_wait": 600,
   "time_range": ["09:00:00-12:00:00", "13:00:00-17:30:00"],
   "time_begin": 1527321492000,
   "time_end": 1527325092000
}

响应示例

{
    "code": 0,  
    "message": "ok",  
    "result": {
       "task_id": "129"
    }     
}

result返回结果集说明

名称 类型 说明
task_id string 任务Id。用于任务数据提交和管理。

提交任务数据

功能:向指定任务提交号码数据,可以分多批次提交。

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/outbound/v1/task/insert?token=08236d0aeeee4d5b566db5f4adc41a63

请求参数说明

名称 必填 类型 说明 备注
task_id string 任务id
call_column string[] 数据列映射
call_list string[][] 数据行 单次上限50条

请求示例

{
   "task_id": "129",
   "call_column": ["客户手机号码","列2", "列3"],
   "call_list": [
         ["13000000001","t2","t3"],
         ["13000000002","t2","t3"]
     ]
}

响应示例

{
    "code": 0,  
    "message": "ok",  
    "result": {
       "total": 2,
       "task_data_ids": [87,88]
    }  
}

result返回结果集说明

名称 类型 说明
total int 号码总数
task_data_ids long[] 外呼数据行对应的任务数据编号,用于结果推送数据关联。

启动外呼任务

功能:启动外呼任务,任务将按照预设的开始时间和工作时段进行外呼。 任务启动之后,将不能再提交号码数据。

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/outbound/v1/task/start?token=08236d0aeeee4d5b566db5f4adc41a63

请求参数说明

名称 必填 类型 说明
task_id string 任务id

请求示例

{
   "task_id": "129"
}

响应示例

{
    "code": 0,  
    "message": "ok",  
    "result": {}     
}

result返回结果集说明

无。通过code响应码表示是否成功。

暂停外呼任务

功能:暂时停止任务呼叫。可以通过启动外呼任务接口恢复任务呼叫。

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/outbound/v1/task/pause?token=08236d0aeeee4d5b566db5f4adc41a63

请求参数说明

名称 必填 类型 说明
task_id string 任务id

请求示例

{
   "task_id": "129"
}

响应示例

{
    "code": 0,  
    "message": "ok",  
    "result": {}     
}

result返回结果集说明

无。通过code响应码表示是否成功。


删除外呼任务

功能:对外呼任务进行强制停止并删除,删除后不能再次启动。

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/outbound/v1/task/delete?token=08236d0aeeee4d5b566db5f4adc41a63

请求参数说明

名称 必填 类型 说明
task_id string 任务id

请求示例

{
   "task_id": "129"
}

响应示例

{
    "code": 0,  
    "message": "ok",  
    "result": {}     
}

result返回结果集说明

无。通过code响应码表示是否成功。

查询任务

功能:查询任务信息和任务列表。

接口地址:https://callapi.xfyun.cn/v1/service/v1/aicall/outbound/v1/task/query?token=08236d0aeeee4d5b566db5f4adc41a63

请求参数说明

名称 必填 类型 说明 备注
task_id string 任务id 用来唯一标识一次请求任务
time_begin long 开始时间
time_end long 结束时间
task_name string 任务名称 模糊检索
page_size int 页大小 最大值50,默认20
page_index int 当前页码 从1开始
sort_name string 排序字段 ID:任务编号,NAME:任务名称,CREATETIME:任务创建时间,STARTTIME:任务开始时间,ENDTIME:任务结束时间
sort_order string 排序字段方式 "ASC" 正序 "DESC" 倒序

请求示例

{
  "time_begin": 153000000
}

响应示例

{
    "code":0,
    "message":"ok",
    "result":{
        "total_rows":30,
        "rows":[
            {
                "task_id":"1909",
                "task_name":"task_test1",
                "status":4,
                "task_type":0,
                "deleted":0,
                "time_task_start":1533289491345,
                "time_task_finish":1533820104848,
                "count_total_task":4,
                "count_tel":4,
                "count_recalled":0,
                "time_task_estimate_begin":1478157571217,
                "time_task_estimate_end":0,
                "line_num":"69101338",
                "robot_id":"719",
                "robot_name":"测试话术无参数",
                "voice_code":"60030",
                "voice_speed":1,
                "count_max_recall":2,
                "status_recall":"[1,1]",
                "time_recall_wait":2000,
                "time_range":"["07:30:00-23:30:00"]",
                "intention_push":"["A","B"]",
                "process_count":7,
                "process_tel_count":7,
                "process_through_count":4,
                "process_through_rate":1
            }
        ]
    }
}

result返回结果集说明

名称 类型 必填 说明 值域
total_rows int 总行数
rows object[] 结果列表
task_id string 任务id
task_name string 任务名称
status int 任务状态 0:新建,1:启动,2:运行,3:暂停,4:完成
task_type int 任务类型 0:普通任务,2:任务池
deleted int 删除标志 1:删除,0:正常
time_task_start long 运行开始时间 毫秒时间戳
time_task_finish long 否(仅限普通任务) 运行结束时间 毫秒时间戳
process_count int 已呼叫次数
process_tel_count int 已呼叫号码数
process_through_count int 已接通量
process_through_rate double 当前接通率
count_tel int 任务号码量
count_recalled int 否(仅限普通任务) 任务已重试次数
time_task_estimate_begin long 否(仅限普通任务) 预设开始时间
time_task_estimate_end long 否(仅限普通任务) 预设结束时间
line_num string 否(仅限普通任务) 线路号码
robot_id string 否(仅限普通任务) 话术id
robot_name string 否(仅限普通任务) 话术名称
voice_code string 否(仅限普通任务) 发音人编码
voice_speed int 否(仅限普通任务) 发音人语速,默认为1
count_max_recall int 否(仅限普通任务) 预设任务重试次数
time_recall_wait int 否(仅限普通任务) 预设重试外呼等待时间 单位:秒。
time_range string 否(仅限普通任务) 预设外呼时间段
intention_push string 否(仅限普通任务) 预设推送意向度门限

结果数据推送

接口协议说明:

请求方向:由开放平台主动请求应用方

请求方式:HTTP POST

字符编码:UTF-8

返回格式:text

对接说明:

应用方应当按照开放平台的数据推送接口协议,实现并提供各类数据接收服务的接口URL地址; 开放平台将会在每通电话结束后,主动向应用方URL进行HTTP POST话单、对话、录音的json数据; 应用方应当立即进行响应,响应内容不限格式,但必须包含success关键字。

强烈建议应用方在接收推送数据时采用异步处理机制,接收到推送数据后立即缓存数据并响应, 然后再使用异步服务对数据进行业务处理,避免因为网络传输、超时等原因造成推送数据丢失。

话单推送

接口模块名称:receiveCallRecord

接口地址:[企业预先配置url]

注意:为了满足应用方对即时性的要求,平台对外呼的话单可能会进行两次推送。两次推送分别为基本属性话单消息和外呼属性话单消息,外呼话单消息中包含基本话单消息的所有字段项,两种消息可以通过是否包含task_row_index属性进行区分。受限于网络等因素,两次话单推送的顺序不做保证。

请求参数说明

名称 必填 类型 说明 备注
business_id string 企业id
app_id string 应用id
robot_id string 话术话术id
call_uuid string 通话UUID 录音和会话的唯一关联。
caller string 主叫号码
callee string 被叫号码
direction int 呼叫方向 1:呼入 2 呼出
time_answer long 接听时间戳 unix_time
time_hangup long 挂断时间戳 unix_time
duration_ring int 拨号振铃时长
duration_call int 通话时长
call_relation_id 仅呼入 string 关联ID 业务侧的唯一标识
task_id 仅呼出 string 外呼任务id
task_data_id 仅呼出 string 外呼任务id
time_dial 仅呼出 long 拨号时间戳 unix_time
time_ring 仅呼出 long 振铃时间戳 unix_time
task_result 仅呼出 string 外呼结果
task_result_desc 仅呼出 string 外呼结果描述
task_tries 仅呼出 int 外呼重试次数
task_row_index 仅呼出 int 外呼数据行号
task_row_head 仅呼出 array 外呼数据行头
task_row_value 仅呼出 array 外呼数据行值

外呼结果说明

task_result task_result_desc 备注
-1 超时
26 网络故障
7 号码错误
0 成功
15 客户接听后并主动挂机
16 客户掉线
3 无法接通 无法接听,无法接通
9 停机 停机,暂停服务,欠费
6 空号 空号,改号
23 呼入限制
22 呼叫转移 呼叫转移失败
4 关机
20 用户未接 回铃音,彩铃,无人接听,用户拒接,来电提醒
5 用户正忙 短忙音,长忙音,静音
2 正在通话中
27 呼出受限 拨号方式不正确
28 线路故障 线路故障,网络忙

请求示例

{
    "business_id":"2745",
    "app_id":"test",
    "robot_id":"2745001",
    "call_uuid":"123425c-6483-11e8-b8fa-2769c24918cd",
    "call_relation_id":"test-123",
    "task_id":"0",
    "task_data_id":"262381",
    "caller":"69102939",
    "callee":"15556985227",
    "direction":1,
    "time_dial":1527737756729,
    "time_ring":1527737757449,
    "time_answer":1527737763429,
    "time_hangup":1527737784829,
    "duration_ring":7,
    "duration_call":28
}

响应结果示例

success

录音推送

接口模块名称:receiveVoice
接口地址:[企业预先配置url]

请求参数说明

名称 必填 类型 说明 备注
business_id string 企业id
app_id string 应用id
robot_id string 话术id
task_data_id string 外呼任务id
call_relation_id string 呼入关联id
call_uuid string 通话UUID
url string url路径
size long 文件大小 字节
duration int 录音长度

请求示例


{
    "call_uuid":"809c825c-6483-11e8-b8db-2769c24918cd",
    "url":"ant/4/ivr/0/2018/05/31/0/452263-7571100e-7afc-42aa-9d69-ac25805d45b6.wav",
    "size":1043244,
    "duration":32,
    "business_id":"10527",
    "app_id":"123",
    "robot_id":"10527"
}

响应结果示例

success

会话推送

接口模块名称:receiveDialog
接口地址:[企业预先配置url]

请求参数说明

名称 必填 类型 说明 备注
business_id string 企业id
app_id string 应用id
robot_id string 话术话术id
task_data_id string 外呼任务id
call_relation_id string 呼入关联id
call_uuid string 通话UUID
tag_max string 最高意向度
tag_min string 最低意向度
dialog array 交互记录
seq int 节点序号
role string 节点角色 robot话术customer客户
node_id string 节点id
node_name string 节点名称
node_type string 节点类型
tag_name string 意向
tag_desc string 意向说明
text_robot string 话术输出内容
text_man string 用户输入内容
question_id String 问题uuid
hits array 命中
hit string 命中内容
pick boolean 是否选中
answer_id string 回答uuid

node_type节点类型说明

node_type 说明
AnyNode 任意回答节点
CollectInputNode 自定义输入节点
ConditionNode 按键输入节点
EndNode 结束节点
HookInfoNode 动态引用节点
KeyNavigationNode 按键导航节点
NoNeedAnswerNode 无需回答节点
NormalNode 普通交互节点

请求示例


{
    "business_id":"10527",
    "app_id":"123",
    "robot_id":"10527",
    "call_uuid":"f3b13ebc-6394-11e8-907d-ebcc4d560c04",
    "dialog":[
        {
            "seq":"3",
            "role":"robot",
            "node_id":"word_node_70601",
            "node_name":"开头语",
            "text_robot":"喂,您好!",
            "text_man":"",
            "question_id":""
        },
        {
            "seq":"4",
            "role":"customer",
            "node_id":"word_node_70601",
            "node_name":"开头语",
            "text_robot":"喂,您好!",
            "text_man":"",
            "question_id":"",
            "hits":[
                {
                    "hit":"任意回答",
                    "pick":true,
                    "answer_id":""
                }
            ]
        }
    ]
}


响应结果示例

success

呼入话术上下文动态数据获取

此接口仅面向电话呼入对接,且话术存在动态数据的业务场景,其它场景可以不实现此接口。

接口协议说明

请求方向:由开放平台在电话呼入时主动请求应用方

请求方式:HTTP POST

字符编码:UTF-8

返回格式:json

对接说明:

应用方应当按照开放平台的接口协议,实现并提供此服务的接口URL地址; 开放平台将会在每通电话开始时,主动向应用方URL进行HTTP POST请求, 获取此通电话对应的话术动态数据并执行。

强烈建议应用方的接口响应时间建议不超过500毫秒,且具备高可用性,避免影响客户电话交互体验。

接口模块名称:getDialogContext
接口地址:[企业预先配置url]

请求参数说明

名称 必填 类型 说明 备注
business_id string 企业id 取自sip头X-business-id
app_id string 应用id 取自sip头X-app-id
robot_id string 话术话术id 取自sip头X-robot-id
call_relation_id string 业务侧关联id 取自sip头X-call-relation-id

请求示例


{
	"call_relation_id":"1111",
	"business_id":"167",
	"app_id":"3333",
	"robot_id":"4444"
}

响应结果说明

map<string,string> 当前通话话术话术要求的上下文动态数据

响应结果示例

{
"key1": "value1",
"性别": "男",
"姓名": "张三"
}

调用示例

请下载 Java Demo

说明:请将Demo中APP_KEY 和 APP_SECRET换成讯飞开放平台提供的appKey和appSecret,详细内容可在相应的应用控制台 ==> 已开通服务中查看。

附录

成功码参照

返回码 说明
0 ok(成功)

服务级错误码参照

错误码 说明
200101 账号或密码错误

系统级错误码参照

错误码 说明
10001 无效的token请求
10002 该token无请求权限
10003 错误的app_id
10004 服务忙,请稍后再试
10005 输入参数不正确
10020 接口维护
10021 接口停用
200200 错误的数据关系
200201 错误的企业id
200202 错误的任务id
200203 错误的外呼号码
200204 错误的话术id
200205 错误的话术发音id
200206 错误的语速
200209 余额不足
200210 错误的文件格式
200211 文件上传超过限定大小10m
200212 错误的数据,与话术动态信息不匹配
200213 上传的外呼数据量超过限制
3030002 号码被占用
3010102 任务已经删除
3010101 任务已经完成

错误码格式说明(示例:200201)

开头 中间 尾部
2 002 01
服务级错误(1为系统级错误) 服务模块代码 具体错误代码