语音机器人开放API

公共信息

接口鉴权

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

HeaderKey	值
Authorization	Bearer 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	否	分页大小

返回数据

名称	类型	备注	其他信息
data	object []
├─ answer_total	integer	应答数
├─ call_period	string	呼叫时间段
├─ called_total	integer	呼叫数
├─ created_at	string	创建时间	utc时区
├─ description	string	任务描述
├─ effect_at	string	生效时间	utc时区
├─ ent_id	integer	企业ID
├─ expire_at	string	过期时间	utc时区
├─ id	integer	任务ID
├─ name	string	任务名称
├─ out_phones	string	外呼号码
├─ phone_total	integer	号码总数
├─ redial	integer	是否重播
├─ redial_interval	integer	重播间隔时长
├─ redial_times	integer	最大重播次数
├─ robot_num	integer	机器人数
├─ running_desc	string	运行说明
├─ skill_id	integer	话术模版ID
├─ skill_name	string	话术模版名称
├─ sms_unanswered	integer	是否未接通发短信
├─ sms_unanswered_template	string	未接通发短信模版
├─ block_enable	int8	是否开启黑名单拦截：0关闭，1开启
├─ block_group_ids	[]int64	黑名单拦截组IDs
├─ task_state	string	任务状态:pending:待开始\|running:进行中\|pausing:暂停中\|finished:已完成\|closed:已结束\|resting:休息中
├─ updated_at	string	更新时间	utc时区
total	integer	总数

语音机器人-任务新增

基本信息

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

Method： POST

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

请求参数

Body

名称	类型	是否必须	备注	其他信息
call_period	string	必须	外呼时段	北京时间，内容为json字符串：[[“00:00:00″,”23:00:00”],[“07:39:37″,”12:39:39”]]
description	string	非必须	任务描述
effect_at	string	必须	生效日期	UTC时区，如：2023-12-17T10:36:12Z
expire_at	string	必须	过期日期	UTC时区，如：2023-12-17T10:36:12Z
name	string	必须	任务名称
out_phones	string	必须	外呼号码	逗号分隔
redial	integer	非必须	是否开启重播
redial_interval	integer	非必须	重播间隔时长
redial_times	integer	非必须	最大重播次数
robot_num	integer	必须	机器人数
skill_id	integer	必须	话术模版ID
sms_unanswered	integer	非必须	是否开启未接通短信
sms_unanswered_template	string	非必须	未接通短信模版ID
block_enable	int8	非必须	是否开启黑名单拦截：0关闭，1开启
block_group_ids	[]int64	非必须	黑名单拦截组IDs

返回数据

名称	类型
task_id	integer

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

基本信息

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

Method： POST

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

请求参数

Body

名称	类型	是否必须	备注	其他信息
encryption_method	string	非必须	加密方式	支持:AES-ECB
phones	object []	必须	外呼号码数组
├─ business_id	string	非必须	业务ID(最长64字符)
├─ phone	string	必须	号码
├─ variables	object	非必须	变量
task_id	integer	必须	外呼任务ID

返回数据

名称	类型	备注
failure_num	integer
success_num	integer

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

基本信息

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

Method： POST

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

请求参数

Body

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

返回数据

名称	类型	备注	其他信息
total	integer	号码总数	必须
data	array[object]		必须
├─ id	integer	号码ID	必须
├─ ent_id	integer	企业ID	必须
├─ task_id	integer	任务ID	必须
├─ skill_id	integer	话术模版ID	必须
├─ batch_no	string	批次号	非必须
├─ phone	string	号码	必须
├─ call_state	string	呼叫状态	必须
├─ answer_state	string	应答状态	必须
├─ intent_tag	array[integer]	意图标签	非必须
├─ last_call_at	string	上一次呼叫时间	非必须
├─ replay_at	string	重播时间	非必须
├─ business_id	string	业务ID	非必须
├─ call_times	integer	呼叫次数	必须

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

基本信息

Path： /unified-api/datagateway/v1/call_robot/tasks/phones

Method： DELETE

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

请求参数

Path 参数

名称	类型	是否必须	说明	备注
task_id	integer	必须	任务ID
phones	array	必须	号码ID	单次最高500条

返回数据

名称	类型	备注
success	boolean	必须

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

基本信息

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

Method： GET

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

请求参数

返回数据

名称	类型	备注	其他信息
	object []
├─ effective_at	string	生效日期	UTC时区
├─ expiration_at	string	过期日期	UTC时区
├─ number	string	主叫号码
├─ number_name	string	号码别名
├─ number_type	integer	号码类型:1呼出\|2呼入\|3呼入呼出

语音机器人-标签列表

基本信息

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

Method： GET

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

请求参数

返回数据

名称	类型	备注
	object []
├─ color	string	标签颜色
├─ id	integer	标签ID
├─ name	string	标签名称
├─ rank	integer	标签排序
├─ type	integer	标签类型

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

基本信息

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

Method： GET

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

请求参数

Query

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

返回数据

名称	类型	备注
data	object []
├─ created_at	string	创建日期
├─ id	integer	话术模版ID
├─ name	string	话术模版名称
├─ type	integer	类型
├─ updated_at	string	更新日期
total	integer	总数

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

基本信息

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	否

返回数据

名称	类型	备注	其他信息
data	object []
├─ answer_at	string	应答时间	UTC时区
├─ answer_state	string	应答状态:answered:正常接通\|not_connected:未接通
├─ billsec	integer	计费时长
├─ billsec_str	string	计费时长_文本
├─ business_id	string	业务ID
├─ call_state	string	呼叫状态:synthesis:待合成\|pending:待开始\|calling:呼叫中\|called:已呼叫\|timeout:已超时\|replay:待重播\|terminated:已终止
├─ callee	string	被叫号码
├─ callee_attribution	string	被叫号码归属地
├─ caller	string	主叫号码
├─ end_at	string	挂机时间
├─ id	integer
├─intent_tags	object[]	意图标签
├──id	integer	意图标签ID
├──name	string	意图标签名称
├─ is_block	boolean	是否为阻止名单
├─ record_file	string	录音文件
├─ redirect	string
├─ ring_time	string
├─ skill_name	string	话术模版名称
├─ start_at	string	呼叫开始时间	UTC时区
├─ task_name	string	任务名称
├─ uuid	string
total	integer

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

基本信息

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

Method： GET

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

请求参数

路径参数

参数名称	示例	备注
uuid

返回数据

名称	类型	备注
answer_at	string	应答时间
answer_state	string	应答状态:answered:正常接通\|not_connected:未接通
billsec	integer	计费时长
billsec_str	string	计费时长_文本
business_id	string	业务ID
call_state	string	呼叫状态:synthesis:待合成\|pending:待开始\|calling:呼叫中\|called:已呼叫\|timeout:已超时\|replay:待重播\|terminated:已终止
callee	string	被叫号码
callee_attribution	string	被叫号码归属地
caller	string	主叫号码
end_at	string	挂机时间
id	integer
intent_tags	object[]	意图标签
├─id	integer	意图标签ID
├─name	string	意图标签名称
is_block	boolean	是否为阻止名单
record_file	string	录音文件
redirect	string
ring_time	string
skill_name	string	话术模版名称
start_at	string	呼叫开始时间
task_name	string	任务名称
uuid	string
call_times	integer	重播轮次
hangup_disposition	integer	挂断方:1-顾客挂断\|2-系统挂断
hangup_case	string	power 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

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

返回数据

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

黑名单分组-列表

基本信息

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

Method： GET

请求参数

无

返回数据

名称	类型	是否必须	备注	其他信息
	object []	非必须		item 类型: object
├─ id	integer	必须	分组ID
├─ name	string	必须	分组名称
├─ created_at	string	必须	创建时间
├─ updated_at	string	必须	更新时间

黑名单分组-删除

基本信息

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

Method： DELETE

请求参数

路径参数

参数名称	备注
groupID	分组ID

返回数据

名称	类型	备注
success	boolean

黑名单分组-编辑

基本信息

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

Method： PUT

请求参数

Body

名称	类型	是否必须	备注
id	integer	必须	分组ID
name	string	必须	分组名称

返回数据

名称	类型	备注
success	boolean

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

基本信息

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

Method： DELETE

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

请求参数

路径参数

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

返回数据

名称	类型	是否必须
success	boolean	非必须

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

基本信息

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

Method： POST

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

请求参数

Body

名称	类型	是否必须	默认值	备注	其他信息
encryption_method	string	非必须		加密方式	支持:AES-ECB
phones	object []	必须		号码
├─ direction	integer	非必须	1	呼叫方向:1呼出\|2呼入\|3呼入呼出
├─ number	string	必须		号码
├─ remark	string	非必须		备注
├─ target	integer	非必须	2	类型:1人工呼叫｜2语音机器人
├─ group_ids	[]int64	非必须		所属的分组ID
├─ expire_at	time.Time	非必须	永久	过期时间

返回数据

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

语音机器人-黑名单列表

基本信息

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

Method： GET

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

请求参数

Query

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

返回数据

名称	类型	备注
data	object []
├─ agent_id	integer	操作人
├─ created_at	string	创建时间
├─ direction	integer	呼叫方向:1呼出\|2呼入\|3呼入呼出
├─ ent_id	integer	企业ID
├─ id	integer
├─ number	string	号码
├─ remark	string	备注
├─ target	integer	类型:1人工呼叫｜2语音机器人
├─ update_at	string	更新时间
total	integer

回调WEBHOOK

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

通话结束

请求参数

名称	类型	是否必须	备注	其他信息
created_at	Number		创建时间戳
enterprise_token	String		企业令牌
event	String		事件类型	语音机器人通话结束call_robot.hangup
id	String		唯一标识符
cdr	object
├─answer_at	string	非必须	应答时间
├─answer_state	string	必须	应答状态:answered:正常接通\|not_connected:未接通
├─billsec	integer	必须	计费时长
├─business_id	string	非必须	业务ID
├─call_state	string	必须	呼叫状态:synthesis:待合成\|pending:待开始\|calling:呼叫中\|called:已呼叫\|timeout:已超时\|replay:待重播\|terminated:已终止
├─callee	string	必须	被叫号码
├─callee_attribution	string	非必须	被叫号码归属地
├─caller	string	必须	主叫号码
├─end_at	string	必须	挂机时间
├─id	integer	必须
├─intent_tags	object[]	非必须	意图标签
├──id	integer	非必须	意图标签ID
├──name	string	非必须	意图标签名称
├─record_file	string	非必须	录音文件
├─skill_name	string	必须	话术模版名称
├─start_at	string	必须	呼叫开始时间
├─task_name	string	必须	任务名称
├─uuid	string	必须

示例

{
                "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_at	Number	创建时间戳
enterprise_token	String	企业令牌
event	String	事件类型	短信发送成功sms.SuccessfulSent
id	String	唯一标识符
sms	object
├─count	number	短信数量
├─failed_code	String	发送失败的情况下的错误代码
├─failed_message	String	发送失败的情况下的错误消息
├─message_state	String	短信状态	SUCCESSFUL_SENT发送成功;FAILED_SENT发送失败
├─send_time	String	发送时间
├─phone	String	手机号码
├─business_id	string	业务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_at	Number	创建时间戳
enterprise_token	String	企业令牌
event	String	事件类型	短信上行回复sms.reply
id	String	唯一标识符
sms	object
├─phone	string	true	手机号
├─reply_content	string	true	用户回复短信内容
├─reply_time	string	true	用户回复短信时间
├─business_id	string	false	业务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 2025年7月24日

本文是否有帮助？

Yes No