1. 首页
  2. 开发指南
  3. 语音机器人开放API

语音机器人开放API

公共信息

接口鉴权

调用开放API接口时,需要在请求的Header中增加鉴权参数。

HeaderKey
AuthorizationBearer access_token

Access Token 您需要在美洽工作台【设置 / 开发者 / APIs】中创建获取。目前 Token 的有效期是永久,重复获取将导致上次获取的 Token 失效。

curl -s https://api.meiqia.com/ -H Authorization:Bearer access_token

通用说明

序号说明
1除特殊说明外,接口均采用application/json传输
2除特殊说明外,入参和出参的时间均为UTC时区

语音机器人-任务列表

基本信息

Path: /unified-api/datagateway/v1/call_robot/tasks/list

Method: GET

接口描述:
语音机器人-任务列表

请求参数

Query

参数名称是否必须备注
page当前页
page_size分页大小

返回数据

名称类型备注其他信息
dataobject []  
├─ answer_totalinteger应答数 
├─ call_periodstring呼叫时间段 
├─ called_totalinteger呼叫数 
├─ created_atstring创建时间utc时区
├─ descriptionstring任务描述 
├─ effect_atstring生效时间utc时区
├─ ent_idinteger企业ID 
├─ expire_atstring过期时间utc时区
├─ idinteger任务ID 
├─ namestring任务名称 
├─ out_phonesstring外呼号码 
├─ phone_totalinteger号码总数 
├─ redialinteger是否重播 
├─ redial_intervalinteger重播间隔时长 
├─ redial_timesinteger最大重播次数 
├─ robot_numinteger机器人数 
├─ running_descstring运行说明 
├─ skill_idinteger话术模版ID 
├─ skill_namestring话术模版名称 
├─ sms_unansweredinteger是否未接通发短信 
├─ sms_unanswered_templatestring未接通发短信模版 
├─ block_enableint8是否开启黑名单拦截:0关闭,1开启 
├─ block_group_ids[]int64黑名单拦截组IDs 
├─ task_statestring任务状态:pending:待开始|running:进行中|pausing:暂停中|finished:已完成|closed:已结束|resting:休息中
├─ updated_atstring更新时间utc时区
totalinteger总数 

语音机器人-任务新增

基本信息

Path: /unified-api/datagateway/v1/call_robot/tasks

Method: POST

接口描述:
语音机器人-任务新增

请求参数

Body

名称类型是否必须备注其他信息
call_periodstring必须外呼时段北京时间,内容为json字符串:[[“00:00:00″,”23:00:00”],[“07:39:37″,”12:39:39”]]
descriptionstring非必须任务描述 
effect_atstring必须生效日期UTC时区,如:2023-12-17T10:36:12Z
expire_atstring必须过期日期UTC时区,如:2023-12-17T10:36:12Z
namestring必须任务名称 
out_phonesstring必须外呼号码逗号分隔
redialinteger非必须是否开启重播 
redial_intervalinteger非必须重播间隔时长 
redial_timesinteger非必须最大重播次数 
robot_numinteger必须机器人数 
skill_idinteger必须话术模版ID 
sms_unansweredinteger非必须是否开启未接通短信 
sms_unanswered_templatestring非必须未接通短信模版ID 
block_enableint8非必须是否开启黑名单拦截:0关闭,1开启 
block_group_ids[]int64非必须黑名单拦截组IDs 

返回数据

名称类型
task_idinteger

语音机器人-外呼任务-添加号码

基本信息

Path: /unified-api/datagateway/v1/call_robot/task/add_phones

Method: POST

接口描述:
语音机器人-外呼任务-添加号码

请求参数

Body

名称类型是否必须备注其他信息
encryption_methodstring非必须加密方式支持:AES-ECB
phonesobject []必须外呼号码数组 
├─ business_idstring非必须业务ID(最长64字符) 
├─ phonestring必须号码 
├─ variablesobject非必须变量 
task_idinteger必须外呼任务ID 

返回数据

名称类型备注
failure_numinteger 
success_numinteger 

语音机器人-外呼任务-任务号码列表

基本信息

Path: /unified-api/datagateway/v1/call_robot/tasks/phones:search

Method: POST

接口描述:
查询一个任务中号码列表

请求参数

Body

名称类型是否必须说明备注
phonestring非必须支持搜索手机号码>=5字符;
<=15字符
tabstring非必须进行中:待拨打、待重播、拨打中的号码;
已完成:结束拨打的号码
号码状况 
ing;
finish
task_idinteger<uint64>必须任务ID >0
sizeinteger<uint64>必须分页数量 默认值20
pageinteger<uint>必须变量 默认值1

返回数据

名称类型备注其他信息
totalinteger号码总数 必须
dataarray[object]   必须
├─ idinteger号码ID 必须
├─ ent_idinteger企业ID 必须
├─ task_idinteger任务ID 必须
├─ skill_idinteger话术模版ID 必须
├─ batch_nostring批次号 非必须
├─ phonestring号码 必须
├─ call_statestring呼叫状态 必须
├─ answer_statestring应答状态 必须
├─ intent_tagarray[integer]意图标签 非必须
├─ last_call_atstring上一次呼叫时间 非必须
├─ replay_atstring重播时间 非必须
├─ business_idstring业务ID 非必须
├─ call_timesinteger呼叫次数 必须

语音机器人-外呼任务-任务号码删除

基本信息

Path: /unified-api/datagateway/v1/call_robot/tasks/{taskID}/{phoneID}

Method: DELETE

接口描述:
支持删除一个任务中还未开始拨打的号码。请注意:
1、这里的删除号码,是将导入的这条拨打记录都删除。
2、待重播的号码,不属于未开始拨打的号码,无法删除

请求参数

Path 参数

名称类型是否必须说明备注
taskIDinteger必须任务ID
phoneIDinteger必须号码ID

返回数据

名称类型备注
successboolean 必须

语音机器人-外显号码列表

基本信息

Path: /unified-api/datagateway/v1/call_robot/out_phones

Method: GET

接口描述:
语音机器人-外显号码列表

请求参数

返回数据

名称类型备注其他信息
 object []  
├─ effective_atstring生效日期UTC时区
├─ expiration_atstring过期日期UTC时区
├─ numberstring主叫号码 
├─ number_namestring号码别名 
├─ number_typeinteger号码类型:1呼出|2呼入|3呼入呼出 

语音机器人-标签列表

基本信息

Path: /unified-api/datagateway/v1/call_robot/intent_tags

Method: GET

接口描述:
语音机器人-标签列表

请求参数

返回数据

名称类型备注其他信息
 object []  
├─ colorstring标签颜色 
├─ idinteger标签ID 
├─ namestring标签名称 
├─ rankinteger标签排序 
├─ typeinteger标签类型 

语音机器人-话术模板列表

基本信息

Path: /unified-api/datagateway/v1/call_robot/skills

Method: GET

接口描述:
语音机器人-话术模板列表

请求参数

Query

参数名称是否必须备注
page 
page_size 

返回数据

名称类型备注其他信息
dataobject []  
├─ created_atstring创建日期 
├─ idinteger话术模版ID 
├─ namestring话术模版名称 
├─ typeinteger类型 
├─ updated_atstring更新日期 
totalinteger总数 

语音机器人-通话记录列表

基本信息

Path: /unified-api/datagateway/v1/call_robot/records/list

Method: GET

接口描述:
语音机器人-通话记录列表

请求参数

Query

参数名称是否必须示例备注
task_id 外呼任务ID
skill_id 话术模版ID
start_at 开始时间
end_at 结束时间
answer_state 应答状态
caller 主叫号码
callee 被叫号码
intent_tag 意图标签
page 当前页
page_size 分页大小
offset  
limit  

返回数据

名称类型备注其他信息
dataobject []  
├─ answer_atstring应答时间UTC时区
├─ answer_statestring应答状态:answered:正常接通|not_connected:未接通 
├─ billsecinteger计费时长 
├─ billsec_strstring计费时长_文本 
├─ business_idstring业务ID 
├─ call_statestring呼叫状态:synthesis:待合成|pending:待开始|calling:呼叫中|called:已呼叫|timeout:已超时|replay:待重播|terminated:已终止 
├─ calleestring被叫号码 
├─ callee_attributionstring被叫号码归属地 
├─ callerstring主叫号码 
├─ end_atstring挂机时间 
├─ idinteger  
├─intent_tagsobject[]意图标签 
├──idinteger意图标签ID 
├──namestring意图标签名称 
├─ is_blockboolean是否为阻止名单 
├─ record_filestring录音文件 
├─ redirectstring  
├─ ring_timestring  
├─ skill_namestring话术模版名称 
├─ start_atstring呼叫开始时间UTC时区
├─ task_namestring任务名称 
├─ uuidstring  
totalinteger  

语音机器人-通话记录详情

基本信息

Path: /unified-api/datagateway/v1/call_robot/records/{uuid}

Method: GET

接口描述:
语音机器人-通话记录详情

请求参数

路径参数

参数名称示例备注
uuid  

返回数据

名称类型备注其他信息
answer_atstring应答时间 
answer_statestring应答状态:answered:正常接通|not_connected:未接通 
billsecinteger计费时长 
billsec_strstring计费时长_文本 
business_idstring业务ID 
call_statestring呼叫状态:synthesis:待合成|pending:待开始|calling:呼叫中|called:已呼叫|timeout:已超时|replay:待重播|terminated:已终止 
calleestring被叫号码 
callee_attributionstring被叫号码归属地 
callerstring主叫号码 
end_atstring挂机时间 
idinteger  
intent_tagsobject[]意图标签 
├─idinteger意图标签ID 
├─namestring意图标签名称 
is_blockboolean是否为阻止名单 
record_filestring录音文件 
redirectstring  
ring_timestring  
skill_namestring话术模版名称 
start_atstring呼叫开始时间 
task_namestring任务名称 
uuidstring  
call_timesinteger重播轮次
hangup_dispositioninteger挂断方:1-顾客挂断|2-系统挂断
hangup_casestringpower off – 关机
does not exist – 空号
out of service – 停机
hold on – 通话中
is not reachable – 用户正忙 无法接通
not answer – 无人接听
not in service – 暂停服务
Bad Request – 请求语法错误
Unauthorized – 请求需要用户验证
Payment Required – 保留,可能用于未来使用
Forbidden – 服务器拒绝请求
Not Found – 服务器无法找到请求的资源
Method Not Allowed – 请求方法不被允许
Not Acceptable – 无法生成客户端接受的响应
Proxy Authentication Required – 需要代理服务器认证
Request Timeout – 请求超时
Gone – 请求的资源永久删除
Request Entity Too Large – 请求实体过大
Request-URI Too Long – 请求的URI过长
Unsupported Media Type – 不支持的媒体类型
Unsupported URI Scheme – 不支持的URI方案
Bad Extension – 扩展字段不正确
Temporarily Unavailable – 被叫方暂时不可用
Call/Transaction Does Not Exist – 呼叫/事务不存在
Loop Detected – 检测到循环
Too Many Hops – 跳数过多
Address Incomplete – 地址不完整
Ambiguous – 地址不明确
Busy Here – 被叫方忙
Request Terminated – 请求被终止
Not Acceptable Here – 此处不可接受
Request Pending – 请求等待中

黑名单分组-新增

基本信息

Path: /unified-api/datagateway/v1/call_robot/black_group

Method: POST

请求参数

Body

名称类型是否必须备注
namestring必须分组名称

返回数据

名称类型是否必须默认值
successboolean非必须 

黑名单分组-列表

基本信息

Path: /unified-api/datagateway/v1/call_robot/black_groups

Method: GET

请求参数

返回数据

名称类型是否必须默认值备注其他信息
 object []非必须  item 类型: object
├─ idinteger必须 分组ID 
├─ namestring必须 分组名称 
├─ created_atstring必须 创建时间 
├─ updated_atstring必须 更新时间 

黑名单分组-删除

基本信息

Path: /unified-api/datagateway/v1/call_robot/black_group/{groupID}

Method: DELETE

请求参数

路径参数

参数名称备注
groupID分组ID

返回数据

名称类型备注
successboolean 

黑名单分组-编辑

基本信息

Path: /unified-api/datagateway/v1/call_robot/black_group

Method: PUT

请求参数

Body

名称类型是否必须备注
idinteger必须分组ID
namestring必须分组名称

返回数据

名称类型备注
successboolean 

语音机器人-黑名单-删除

基本信息

Path: /unified-api/datagateway/v1/call_robot/black_lists/{blackID}

Method: DELETE

接口描述:
语音机器人-黑名单-删除

请求参数

路径参数

参数名称示例备注
blackID 黑名单ID

返回数据

名称类型是否必须
successboolean非必须

语音机器人-黑名单-导入号码

基本信息

Path: /unified-api/datagateway/v1/call_robot/black_lists/import

Method: POST

接口描述:
语音机器人-黑名单-导入号码

请求参数

Body

名称类型是否必须默认值备注其他信息
encryption_methodstring非必须 加密方式支持:AES-ECB
phonesobject []必须 号码 
├─ directioninteger非必须1呼叫方向:1呼出|2呼入|3呼入呼出 
├─ numberstring必须 号码 
├─ remarkstring非必须 备注 
├─ targetinteger非必须2类型:1人工呼叫|2语音机器人 
├─ group_ids[]int64非必须 所属的分组ID 
├─ expire_attime.Time非必须永久过期时间 

返回数据

名称类型是否必须默认值备注其他信息
successboolean非必须   

语音机器人-黑名单列表

基本信息

Path: /unified-api/datagateway/v1/call_robot/black_lists

Method: GET

接口描述:
语音机器人-黑名单列表

请求参数

Query

参数名称是否必须示例备注
number 号码
direction 呼叫方向
page_size 分页大小
page 当前页

返回数据

名称类型备注其他信息
dataobject []  
├─ agent_idinteger操作人 
├─ created_atstring创建时间 
├─ directioninteger呼叫方向:1呼出|2呼入|3呼入呼出 
├─ ent_idinteger企业ID 
├─ idinteger  
├─ numberstring号码 
├─ remarkstring备注 
├─ targetinteger类型:1人工呼叫|2语音机器人 
├─ update_atstring更新时间 
totalinteger  

回调WEBHOOK

Webhooks 是 2021 全新在线客服企业版、旗舰版功能,点击我前往工作台设置页。

通话结束

请求参数

名称类型是否必须备注其他信息
created_atNumber 创建时间戳 
enterprise_tokenString 企业令牌 
eventString 事件类型语音机器人通话结束call_robot.hangup
idString 唯一标识符 
cdrobject   
├─answer_atstring非必须应答时间 
├─answer_statestring必须应答状态:answered:正常接通|not_connected:未接通 
├─billsecinteger必须计费时长 
├─business_idstring非必须业务ID 
├─call_statestring必须呼叫状态:synthesis:待合成|pending:待开始|calling:呼叫中|called:已呼叫|timeout:已超时|replay:待重播|terminated:已终止 
├─calleestring必须被叫号码 
├─callee_attributionstring非必须被叫号码归属地 
├─callerstring必须主叫号码 
├─end_atstring必须挂机时间 
├─idinteger必须  
├─intent_tagsobject[]非必须意图标签 
├──idinteger非必须意图标签ID 
├──namestring非必须意图标签名称 
├─record_filestring非必须录音文件 
├─skill_namestring必须话术模版名称 
├─start_atstring必须呼叫开始时间 
├─task_namestring必须任务名称 
├─uuidstring必须  

示例

{
                "id":"xxxxxx",
                "event":"call_robot.hangup",
                "enterprise_token":"xxxxxx",
                "created_at":1702971650,
                "cdr":{
                    "id":1,
                    "ent_id":1,
                    "task_id":1,
                    "uuid":"xxxxxx",
                    "callee":"173xxxx5659",
                    "callee_attribution":"四川/成都",
                    "task_name":"日常测试",
                    "skill_name":"",
                    "call_state":"called",
                    "answer_state":"answered",
                    "caller":"081xxxxx853",
                    "start_at":"2023-12-19 07:40:35.037255869 +0000 UTC",
                    "end_at":"2023-12-19 07:40:47.546662962 +0000 UTC",
                    "answer_at":"2023-12-19 07:40:39.978848 +0000 UTC",
                    "billsec":8,
                    "record_file":"https://meiqia.com/rexxxxxxx3127e7.wav",
                    "intent_tag": [60,62],
                    "intent_tags": [
                        {
                            "id": 60,
                            "type": "自定义",
                            "name": "A级明确意向",
                            "color": "#e8f3ff",
                            "rank": 10000
                        },
                        {
                            "id": 62,
                            "type": "自定义",
                            "name": "B级一般意向",
                            "color": "#e8f3ff",
                            "rank": 10000
                        },
                    ],
                    "business_id":"1122"
                }
            }
        

短信-发送成功回调

请求参数

参数类型备注说明
created_atNumber创建时间戳 
enterprise_tokenString企业令牌 
eventString事件类型短信发送成功sms.SuccessfulSent
idString唯一标识符 
smsobject  
├─countnumber短信数量 
├─failed_codeString发送失败的情况下的错误代码 
├─failed_messageString发送失败的情况下的错误消息 
├─message_stateString短信状态SUCCESSFUL_SENT发送成功;FAILED_SENT发送失败
├─send_timeString发送时间 
├─phoneString手机号码 
├─business_idstring业务ID 

参考示例

{
                "created_at":1702954643,
                "enterprise_token":"xxxx",
                "event":"sms.SuccessfulSent",
                "id":"xxxx",
                "sms":{
                    "count":0,
                    "failed_code":"",
                    "failed_message":"",
                    "message_state":"SUCCESSFUL_SENT",
                    "send_time":"2023-05-12 11:32:14",
                    "phone":"1300000001719",
                    "business_id":""
                }
            }

短信-上行回复推送接口

请求参数

参数名类型必传说明备注
created_atNumber创建时间戳  
enterprise_tokenString企业令牌  
eventString事件类型短信上行回复sms.reply 
idString唯一标识符  
smsobject   
├─phonestringtrue手机号 
├─reply_contentstringtrue用户回复短信内容 
├─reply_timestringtrue用户回复短信时间 
├─business_idstringfalse业务ID 

推送示例

   {
                "created_at":1702954643,
                "enterprise_token":"xxxx",
                "event":"sms.reply",
                "id":"xxxx",
                "sms":{
                    "phone": "15959595959",
                    "reply_content": "好的",
                    "reply_time": "2023-05-12 11:32:14",
                    "business_id": "1658394963077787648"
                }
            }
Updated on 2024年10月9日

本文是否有帮助?

您可能想了解