语音机器人接口对接

注：使用openapi接口前，首先需要参照接口鉴权说明完成鉴权

本文档用于第三方系统接入 UE 智能外呼服务，包含以下接口：

序号	接口	请求方式	请求路径
1	分页查询 Agent 列表	POST	/openapi/agent/web/v1/agent/query
2	分页查询号码组列表	POST	/openapi/agent/web/v1/number/group/query
3	创建智能外呼任务	POST	/openapi/agent/web/v1/callTask/create
4	导入外呼客户数据	POST	/openapi/agent/web/v1/callTask/import
5	查询外呼任务列表与进度	POST	/openapi/agent/web/v1/callTask/query
6	启动或暂停外呼任务	POST	/openapi/agent/web/v1/callTask/operate

1.请求协议

请求协议：HTTPS

数据格式：JSON

字符编码：UTF-8

请求头 Content-Type：application/json

2.身份标识

所有接口必须在请求头中传入客户的租户标识：

请求头	类型	必填	说明
appId	String	是	UE 分配的租户标识
Content-Type	String	是	固定为 application/json

请求头示例：

Content-Type: application/json
appId: tenant-demo

请妥善保管 appId，不得在不同客户或租户之间混用。

3.通用响应结构

所有接口均返回以下统一结构：

字段	类型	说明
code	Integer	业务状态码，200 表示成功，非 200 表示失败
data	Object	响应数据；失败时可能为 null
message	String	响应说明；失败时返回错误原因
traceId	String	请求追踪标识，排查问题时请提供该值

成功响应示例：

{
  "code": 200,
  "data": {},
  "message": null,
  "traceId": "68649f1fc6b8a67d3a732611"
}

失败响应示例：

{
  "code": 400,
  "data": null,
  "message": "appId不能为空",
  "traceId": "68649f1fc6b8a67d3a732611"
}

4.分页响应结构

分页接口的 data 字段结构如下：

字段	类型	说明
pageNum	Integer	当前页码，从 1 开始
pageSize	Integer	每页条数，最大为 500
total	Integer	符合条件的总记录数
list	Array	当前页数据列表
hasNext	Boolean	是否存在下一页

{
  "code": 200,
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 1,
    "list": [],
    "hasNext": false
  },
  "message": null,
  "traceId": "68649f1fc6b8a67d3a732611"
}

5.推荐调用顺序

调用 Agent 列表接口，获取用于外呼任务的 voiceAgentId。
调用号码组列表接口，获取外呼主叫号码组的 id。
调用任务创建接口，获取 taskId。
用客户数据导入接口，向任务导入被叫客户。
调用任务操作接口启动或暂停任务。
调用任务查询接口，查询任务状态和执行进度。

查询当前租户下可用于创建外呼任务的 Agent。

1.1请求路径

POST /openapi/agent/web/v1/agent/query

1.2请求参数

字段	类型	必填	说明
pageNo	Integer	是	当前页码，从 1 开始
pageSize	Integer	是	每页条数，最大为 500
name	String	否	Agent 名称，支持模糊查询

1.3请求示例

{
  "pageNo": 1,
  "pageSize": 10,
  "name": "回访"
}

1.4响应参数

data.list 中的 Agent 对象字段如下

字段	类型	说明
id	Long	Agent ID，创建外呼任务时作为 voiceAgentId 传入
name	String	Agent 名称
answerSource	String	回答来源
description	String	Agent 描述
callInOut	Integer	呼入呼出类型
voice	String	使用的音色
language	String	使用的语言
wakeUpEnabled	Boolean	是否启用主动唤醒
followUpInterval	Integer	追问间隔
maxFollowUpCount	Integer	最大追问次数
publishStatus	String	发布状态，取值见“枚举说明”
version	String	Agent 版本类型，例如 2、3
createTime	String	创建时间
updateTime	String	更新时间

1.5响应示例

{
  "code": 200,
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 1,
    "list": [
      {
        "id": 10001,
        "name": "客户回访Agent",
        "answerSource": "LLM",
        "description": "用于活动客户回访",
        "callInOut": 2,
        "voice": "female_01",
        "language": "zh-CN",
        "wakeUpEnabled": true,
        "followUpInterval": 5,
        "maxFollowUpCount": 2,
        "publishStatus": "PUBLISHED",
        "version": "3",
        "createTime": "2026-08-01 10:00:00",
        "updateTime": "2026-08-01 11:00:00"
      }
    ],
    "hasNext": false
  },
  "message": null,
  "traceId": "68649f1fc6b8a67d3a732611"
}

查询当前租户下可用于智能外呼的主叫号码组。

2.1请求路径

POST /openapi/agent/web/v1/number/group/query

2.2请求参数

字段	类型	必填	说明
pageNo	Integer	是	当前页码，从 1 开始
pageSize	Integer	是	每页条数，最大为 500
groupName	String	否	号码组名称，支持模糊查询

2.3请求示例

{
  "pageNo": 1,
  "pageSize": 10,
  "groupName": "默认号码组"
}

2.4响应参数

data.list 中的号码组对象字段如下：

字段	类型	说明
id	Long	号码组 ID，创建任务时作为 callerNumberGroupId 传入
groupName	String	号码组名称
strategy	String	号码选择策略
strategyName	String	号码选择策略中文名称
displayNumbers	String	显示号码列表，内容为 JSON 数组字符串
defaultNumbers	String	默认号码列表，内容为 JSON 数组字符串
status	Integer	状态：0 禁用，1 启用
createTime	String	创建时间
updateTime	String	更新时间

2.5响应示例

{
  "code": 200,
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 1,
    "list": [
      {
        "id": 1001,
        "groupName": "默认外呼号码组",
        "strategy": "RANDOM",
        "strategyName": "随机",
        "displayNumbers": "[\"02812345678\"]",
        "defaultNumbers": "[\"02812345678\"]",
        "status": 1,
        "createTime": "2026-08-01 10:00:00",
        "updateTime": "2026-08-01 11:00:00"
      }
    ],
    "hasNext": false
  },
  "message": null,
  "traceId": "68649f1fc6b8a67d3a732611"
}

创建一个智能外呼任务。创建成功后返回任务 ID，客户数据需通过“导入外呼客户数据”接口单独导入。

3.1请求路径

POST /openapi/agent/web/v1/callTask/create

3.2请求参数

字段	类型	必填	说明
taskName	String	是	任务名称，最多 50 个字符
voiceAgentId	Long	是	Agent ID，必须大于 0
startType	String	是	启动策略：manual 或 scheduled
scheduledStartTime	String	条件必填	定时任务必填，格式为 yyyy-MM-dd HH:mm:ss，且必须晚于当前时间；手动任务不得传入
callStrategy	Object	是	呼叫策略
retryStrategy	Object	是	重呼策略

callStrategy 字段：

字段	类型	必填	说明
callWindowRanges	Array	是	可呼叫时间窗口，至少一组
maxConcurrency	Integer	是	任务最大并发数，必须大于 0
callerNumberGroupId	String	是	当前租户下已存在的外呼号码组 ID，必须为大于 0 的数字字符串
callerNumberGroupName	String	否	外呼号码组名称

callWindowRanges 数组元素字段：

字段	类型	必填	说明
callWeekdays	Integer[]	是	可呼叫星期，1 至 7 分别表示星期一至星期日，不能重复
callTimeRanges	String[]	是	可呼叫时间段，格式为 HH:mm-HH:mm，结束时间必须晚于开始时间

retryStrategy 字段：

字段	类型	必填	说明
retryEnabled	Boolean	是	是否启用重呼
retryReasons	String[]	条件必填	启用重呼时必填，取值见“枚举说明”
maxRetryTimes	Integer	条件必填	启用重呼时必填，最大重呼次数，必须大于 0
retryIntervalValue	Integer	条件必填	启用重呼时必填，重呼间隔值，必须大于 0
retryIntervalUnit	String	条件必填	启用重呼时必填，单位为 minute 或 day

3.3请求示例

手动启动任务请求示例：

{
  "taskName": "8月客户回访任务",
  "voiceAgentId": 10001,
  "agentType": "voiceagent",
  "startType": "manual",
  "callStrategy": {
    "callWindowRanges": [
      {
        "callWeekdays": [1, 2, 3, 4, 5],
        "callTimeRanges": ["09:00-12:00", "14:00-18:00"]
      }
    ],
    "maxConcurrency": 10,
    "callerNumberGroupId": "10001",
    "callerNumberGroupName": "默认外呼号码组"
  },
  "retryStrategy": {
    "retryEnabled": true,
    "retryReasons": ["busy", "no_answer"],
    "maxRetryTimes": 2,
    "retryIntervalValue": 10,
    "retryIntervalUnit": "minute"
  }
}

定时启动任务需使用以下字段：

{
  "startType": "scheduled",
  "scheduledStartTime": "2026-08-11 09:00:00"
}

关闭重呼时，retryStrategy 示例：

{
  "retryEnabled": false,
  "retryReasons": [],
  "maxRetryTimes": null,
  "retryIntervalValue": null,
  "retryIntervalUnit": null
}

3.4响应参数

字段	类型	说明
taskId	String	新建任务 ID
status	String	任务状态，取值见“枚举说明”

3.5响应示例

{
  "code": 200,
  "data": {
    "taskId": "1939900000000000001",
    "status": "draft"
  },
  "message": null,
  "traceId": "68649f1fc6b8a67d3a732611"
}

向已创建的外呼任务批量导入被叫客户。单次请求最多导入 10000 条数据。

4.1请求路径

POST /openapi/agent/web/v1/callTask/import

4.2请求参数

字段	类型	必填	说明
taskId	String	是	外呼任务 ID，必须为大于 0 的数字字符串
customers	Array	是	客户数据列表，数量为 1 至 10000 条
dupStrategy	String	否	task：任务去重 batch：当前导入批次去冲 none：不去重。默认为batch

customers 数组元素字段：

字段	类型	必填	说明
customerNumber	String	是	客户号码，支持数字、+、-，长度为 5 至 20 个字符
customerName	String	否	客户名称，最多 100 个字符
remark	String	否	备注，最多 500 个字符
variables	Object	否	自定义变量，最多 20 个；变量名最多 50 个字符，变量值最多 500 个字符

variables 用于向 Agent 传递当前客户的个性化信息，例如姓名、城市、订单号等。变量名应与 Agent 中配置的变量保持一致。

4.3请求示例

{
  "taskId": "1939900000000000001",
  "customers": [
    {
      "customerNumber": "13800000000",
      "customerName": "张三",
      "remark": "重点客户",
      "variables": {
        "city": "成都",
        "orderNo": "ORDER-20260810-001"
      }
    },
    {
      "customerNumber": "13900000000",
      "customerName": "李四",
      "variables": {
        "city": "重庆"
      }
    }
  ]
}

4.4响应参数

字段	类型	说明
taskId	String	外呼任务 ID
importBatchId	Long	本次导入批次 ID
fileType	String	导入类型，JSON 接口固定返回 json
totalCount	Integer	本次提交的数据总数
successCount	Integer	导入成功数量
emptyCount	Integer	空数据数量
invalidCount	Integer	无效数据数量
failureCount	Integer	导入失败数量
failureReasons	String	失败原因汇总；无失败数据时可能为 null

4.5响应示例

{
  "code": 200,
  "data": {
    "taskId": "1939900000000000001",
    "importBatchId": 1939900000000000100,
    "fileType": "json",
    "totalCount": 2,
    "successCount": 2,
    "emptyCount": 0,
    "invalidCount": 0,
    "failureCount": 0,
    "failureReasons": null
  },
  "message": null,
  "traceId": "68649f1fc6b8a67d3a732611"
}

注意：接口调用成功仅表示本次导入处理完成。是否存在单条失败数据，应以 successCount、failureCount 和 failureReasons 为准。

分页查询当前租户下的全部外呼任务。每条记录同时返回任务状态、执行进度以及 /v1/outbound/tasks/{id} 详情接口包含的完整任务配置。

5.1请求路径

POST /openapi/agent/web/v1/callTask/query

5.2请求参数

字段	类型	必填	说明
pageNum	Integer	是	当前页码，从 1 开始
pageSize	Integer	是	每页条数，最大为 500
query	Object	否	查询条件；不传或传空对象 {} 时分页查询全部任务

query 字段：

字段	类型	必填	说明
taskName	String	否	任务名称，支持模糊查询，最多 50 个字符
startDate	String	否	创建日期开始值，格式为 yyyy-MM-dd
endDate	String	否	创建日期结束值，格式为 yyyy-MM-dd，不得早于 startDate
statusList	String[]	否	任务状态列表，取值见“枚举说明”

5.3请求示例

{
  "pageNum": 1,
  "pageSize": 10,
  "query": {
    "taskName": "客户回访",
    "startDate": "2026-08-01",
    "endDate": "2026-08-31",
    "statusList": ["draft", "running", "done"]
  }
}

查询全部任务时：

{
  "pageNum": 1,
  "pageSize": 100
}

5.4响应参数

data.list 中的任务对象字段如下：

字段	类型	说明
id	String	外呼任务 ID
taskName	String	任务名称
voiceAgentId	Long	Agent ID
voiceAgentName	String	Agent 名称
agentType	String	Agent 类型
createUser	String	创建人
createTime	String	创建时间
updateUser	String	更新人
updateTime	String	更新时间
startType	String	启动策略
scheduledStartTime	String	定时启动时间；手动启动任务可能为 null
callStrategy	Object	呼叫策略，字段与创建任务接口中的 callStrategy 一致
retryStrategy	Object	重呼策略，字段与创建任务接口中的 retryStrategy 一致；未配置时可能为 null
lastExecutedTime	String	最近执行时间
totalCount	Integer	任务客户总数
completedCount	Integer	已完成呼叫数量
connectedCount	Integer	已接通数量
progressRate	Decimal	执行进度，范围 0 至 1；例如 0.75 表示 75%
status	String	任务状态，取值见“枚举说明”
maxConcurrency	Integer	任务最大并发数

5.5响应示例

{
  "code": 200,
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 1,
    "list": [
      {
        "id": "1939900000000000001",
        "taskName": "8月客户回访任务",
        "voiceAgentId": 10001,
        "voiceAgentName": "客户回访 Agent",
        "agentType": "voiceagent",
        "createUser": "系统管理员[admin]",
        "createTime": "2026-08-10 15:30:00",
        "updateUser": "系统管理员[admin]",
        "updateTime": "2026-08-10 16:00:00",
        "startType": "manual",
        "scheduledStartTime": null,
        "callStrategy": {
          "callWindowRanges": [
            {
              "callWeekdays": [1, 2, 3, 4, 5],
              "callTimeRanges": ["09:00-12:00", "14:00-18:00"]
            }
          ],
          "maxConcurrency": 10,
          "callerNumberGroupId": "1001",
          "callerNumberGroupName": "默认外呼号码组"
        },
        "retryStrategy": {
          "retryEnabled": true,
          "retryReasons": ["busy", "no_answer"],
          "maxRetryTimes": 2,
          "retryIntervalValue": 10,
          "retryIntervalUnit": "minute"
        },
        "lastExecutedTime": "2026-08-10T16:00:00",
        "totalCount": 1000,
        "completedCount": 750,
        "connectedCount": 520,
        "progressRate": 0.75,
        "status": "running",
        "maxConcurrency": 10
      }
    ],
        "hasNext": false
  },
  "message": null,
  "traceId": "68649f1fc6b8a67d3a732611"
}

根据 operation 对当前租户下的外呼任务执行启动或暂停操作。

6.1请求路径

POST /openapi/agent/web/v1/callTask/operate

6.2请求参数

字段	类型	必填	说明
taskId	String	是	外呼任务 ID，必须为大于 0 的数字字符串
operation	String	是	操作类型：start 启动任务，pause 暂停任务

6.3请求示例

启动任务请求示例：

{
  "taskId": "1939900000000000001",
  "operation": "start"
}

暂停任务请求示例：

{
  "taskId": "1939900000000000001",
  "operation": "pause"
}

6.4响应参数

字段	类型	说明
taskId	String	外呼任务 ID
status	String	操作后的任务状态，取值见“外呼任务状态”
operatedTime	String	操作时间

6.5响应示例

{
  "code": 200,
  "data": {
    "taskId": "1939900000000000001",
    "status": "running",
    "operatedTime": "2026-08-11T18:00:00"
  },
  "message": null,
  "traceId": "68649f1fc6b8a67d3a732611"
}

启动任务时，任务必须处于允许启动的状态且已导入可呼叫客户；暂停任务时，任务必须处于运行中状态。

错误码	信息	触发条件
702	外显号码组不存在	创建任务时号码组不存在，或不属于当前租户
801	task.not.exist	查询或操作的任务不存在
803	task.agent.not.found	创建任务时 Agent 不存在，或 Agent 类型不支持
806	task.invalid.start.state	任务当前状态不允许启动
807	task.invalid.pause.state	任务当前状态不允许暂停
809	task.invalid.import.state	任务当前状态不允许导入客户
810	task.invalid.edit.state	任务当前状态不允许编辑
813	task.call.pool.empty	启动任务时没有可呼叫客户

当查询接口同时传入 startDate 和 endDate 时，endDate 不能早于 startDate，否则返回参数校验错误。

1 Agent 类型

值	说明
voicebot	语音机器人
voiceagent	语音 Agent

2 Agent 发布状态

值	说明
PUBLISHED	已发布
OFFLINE	已下线
NEVER_PUBLISHED	从未发布

创建外呼任务时，建议选择 publishStatus 为 PUBLISHED 的 Agent。

3 任务启动策略

值	说明
manual	手动启动
scheduled	定时启动

4 外呼任务状态

值	说明
draft	草稿
running	运行中
pause	已暂停
done	已完成

5 号码组策略

值	说明
RANDOM	随机选择号码
RR_MEMORY	轮询选择号码
AREA_CODE	按被叫号码归属地选择号码

6 重呼原因

值	说明
unreachable	无法接通
busy	占线
no_answer	无人接听
rejected	拒接
voice_assistant	语音助手接听
power_off	关机

7 重呼间隔单位

值	说明
minute	分钟
day	天

以下示例演示如何查询 Agent 列表：

curl --request POST '{baseUrl}/openapi/agent/web/v1/agent/query' \
  --header 'Content-Type: application/json' \
  --header 'appId: tenant-demo' \
  --data '{
    "pageNo": 1,
    "pageSize": 10
  }'

2026-08-20

语音机器人接口对接

文档说明

接入约定

1.分页查询 Agent 列表

2.分页查询号码组列表

3.创建智能外呼任务

4.导入外呼客户数据

5.查询外呼任务列表与进度

6.启动或暂停外呼任务

外呼任务错误码

枚举说明

调用示例

本页目录