NXLINK AI taskCreate - nxtele/http-api-document GitHub Wiki

创建外呼任务

URL：https://api-hk.nxlink.ai/openapi/aiagent/task/create
Method：POST
Content-Type：application/json
需要鉴权：是

🌐 服务接入点

NXLink 在全球部署了多个服务区域，请根据您的业务所在地选择对应的服务接入点。不同区域的网站域名和API网关域名不同。

代号	区域	NXLink网站	API网关
APAC	香港	`https://app.nxlink.ai`	`https://api-hk.nxlink.ai`
AMER	美洲	`https://chl-nxlink.nxcloud.com`	`https://chl-api.nxlink.ai`
APAC(IDN)	印尼	`https://idn.nxlink.ai`	`https://api-idn.nxlink.ai`

请求参数

header参数：

参数名	类型	必选	示例值	说明
accessKey	String	是	AK-6230339248928541113-2133	用户身份标识
ts	String	是	1655710885431	当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType	String	是	100	业务类型，取固定值“100”
action	String	是	nxai	业务操作，取固定值“nxai”
sign	String	是	6e9506557d1f289501d333ee2c365826	API入参参数签名查看公共约定，签名算法

请求参数：

参数名	类型	必选	示例值	说明
userTaskId	String	否	"EXT-TASK-202603250001"	用户自定义任务id，建议全局唯一，便于对账和查询
other	String	否	"task-batch-20260325"	任务透传字段，会在任务状态回调和查询任务列表接口中原样返回
taskName	String	是	"客户回访任务-0325"	任务名称
taskDesc	String	否	"针对已下单客户进行满意度回访"	任务描述
autoFlowId	Long	是	197	AI Agent id，可通过查询AI Agent列表获取
routeId	String	是	"y29ND1X4kkCG_nC576sALEkvg3HjEqde"	呼叫路由id，可通过查询呼叫路由列表获取
taskKeep	Integer	是	0	是否永久任务，0:否，1:是
startupType	Integer	是	1	启动方式，1:手动启动，2:定时启动，3:立即启动
startupAt	Long	否	1746583929	`startupType=2` 时必填，定时启动的秒级时间戳
shutdownAt	Long	否	1746670329	定时停止的秒级时间戳；不传表示不设置停止时间
zoneSecond	Integer	是	28800	任务工作时区偏移秒数，例如东八区为 `28800`
weekDay	String	是	"1,2,3,4,5,6,7"	允许拨打的星期，多个用英文逗号分隔，1:周一，...，7:周日
firstFifteen	String	是	"9,10,11,14,15,16,17"	每小时第1个15分钟可拨打的小时段，对应 `HH:00~HH:15`
secondFifteen	String	是	"9,10,11,14,15,16,17"	每小时第2个15分钟可拨打的小时段，对应 `HH:15~HH:30`
thirdFifteen	String	是	"9,10,11,14,15,16,17"	每小时第3个15分钟可拨打的小时段，对应 `HH:30~HH:45`
fourthFifteen	String	是	"9,10,11,14,15,16,17"	每小时第4个15分钟可拨打的小时段，对应 `HH:45~HH+1:00`
orderMaxCall	Integer	是	1	单个号码最大重拨次数
replayInterval	Integer	是	600	重拨间隔，单位秒；例如10分钟传 `600`
maxCall	Integer	否	20	最大通话并发，`0` 表示按系统默认值处理
maxRingTime	Integer	否	40	最大响铃时长，单位秒，`0` 表示按系统默认值处理
taskCallbackUrl	String	否	"https://example.com/webhook/task"	任务状态回调地址
callCallbackUrl	String	否	"https://example.com/webhook/call"	通话结束回调地址；优先使用API传入值，未传则使用页面配置，页面也未配置则不回调
countryCode	String	否	"86"	默认国码；当 `callList` 中号码未携带国家码时可传
callList	Array	否		创建任务时同时导入的名单信息；不传或空数组表示仅创建空任务，后续可通过追加名单接口导入

callList元素

参数名	类型	必选	示例值	说明
contactId	String	是	"52145b00-abc9-4a87-94c2-ed1e1e42x4rfvmh"	名单id（全局唯一）
other	String	否	"contact-ext-001"	名单透传字段，会在通话记录回调中原样返回
name	String	是	"Jones"	用户名称
phoneNumber	String	是	"13800000001"	用户号码
params	Array	否		变量信息

params元素

参数名	类型	必选	示例值	说明
name	String	是	"customerName"	变量名称（必须和流程中已存在的变量名称一致）
value	Object	否	"Lucy"	变量值

启动方式(startupType)说明

值	说明
1	手动启动
2	定时启动
3	立即启动

拨打时间窗口字段说明

字段	取值范围	说明
weekDay	1~7	允许拨打的星期，1:周一，...，7:周日
firstFifteen	0~23	对应每个小时的 `00~15` 分钟
secondFifteen	0~23	对应每个小时的 `15~30` 分钟
thirdFifteen	0~23	对应每个小时的 `30~45` 分钟
fourthFifteen	0~23	对应每个小时的 `45~60` 分钟

说明

如果本次只创建空任务，可省略 callList 或传空数组，后续再调用追加名单接口导入联系人。

请求示例

请求body：

{
  "userTaskId": "EXT-TASK-202603250001",
  "other": "task-batch-20260325",
  "taskName": "客户回访任务-0325",
  "taskDesc": "针对已下单客户进行满意度回访",
  "autoFlowId": 197,
  "routeId": "y29ND1X4kkCG_nC576sALEkvg3HjEqde",
  "taskKeep": 0,
  "startupType": 2,
  "startupAt": 1746583929,
  "shutdownAt": 1746670329,
  "zoneSecond": 28800,
  "weekDay": "1,2,3,4,5,6,7",
  "firstFifteen": "9,10,11,14,15,16,17",
  "secondFifteen": "9,10,11,14,15,16,17",
  "thirdFifteen": "9,10,11,14,15,16,17",
  "fourthFifteen": "9,10,11,14,15,16,17",
  "orderMaxCall": 1,
  "replayInterval": 600,
  "maxCall": 20,
  "maxRingTime": 40,
  "taskCallbackUrl": "https://example.com/webhook/task",
  "callCallbackUrl": "https://example.com/webhook/call",
  "countryCode": "86",
  "callList": [
    {
      "contactId": "c3d79370-9f3a-4da2-84dd-2d2200f40e11",
      "other": "contact-ext-001",
      "name": "Lucy",
      "phoneNumber": "13800000001",
      "params": [
        {
          "name": "customerName",
          "value": "Lucy"
        },
        {
          "name": "orderNo",
          "value": "SO202603250001"
        }
      ]
    },
    {
      "contactId": "5f6f6f6f-7a7b-4c4d-9e9f-101010101010",
      "other": "contact-ext-002",
      "name": "Tom",
      "phoneNumber": "13800000002",
      "params": [
        {
          "name": "customerName",
          "value": "Tom"
        }
      ]
    }
  ]
}

响应参数

参数名	类型	说明
code	Integer	结果编码
message	String	请求结果说明
traceId	String	链路追踪ID
data	Object	响应数据主体

data对象

参数名	类型	说明
taskId	String	创建成功后的任务id
userTaskId	String	用户自定义任务id
taskStatus	Integer	任务状态，1:准备就绪，2:进行中，3:已完成，4:失败，5:已暂停，6:余额不足暂停
successCount	Integer	成功导入的记录数量
totalCount	Integer	总共处理的记录数量
errList	Array	错误列表，包含导入失败的记录信息

errList元素

参数名	类型	说明
contactId	String	导入失败的名单id，作为错误记录的唯一标识
name	String	用户名称
phoneNumber	String	导入失败的电话号码
errMsg	String	失败原因

响应示例

成功示例

{
  "code": 0,
  "message": "success",
  "traceId": "3287f5aa-b8db-4dd7-97b0-03fabac2f4c7",
  "data": {
    "taskId": "52145b00-abc9-4a87-94c2-ed1e1e42ec1c",
    "userTaskId": "EXT-TASK-202603250001",
    "taskStatus": 1,
    "successCount": 2,
    "totalCount": 2,
    "errList": []
  }
}

部分导入失败示例

{
  "code": 0,
  "message": "success",
  "traceId": "dbdd93a9-cb7c-4c0d-8f98-01755b1883b6",
  "data": {
    "taskId": "52145b00-abc9-4a87-94c2-ed1e1e42ec1c",
    "userTaskId": "EXT-TASK-202603250001",
    "taskStatus": 1,
    "successCount": 1,
    "totalCount": 2,
    "errList": [
      {
        "contactId": "5f6f6f6f-7a7b-4c4d-9e9f-101010101010",
        "name": "lucy",
        "phoneNumber": "1312895-xxx",
        "errMsg": "Illegal phone number format:1312895-xxx"
      }
    ]
  }
}

失败示例

{
  "code": 20000,
  "message": "autoFlowId not found",
  "traceId": "8a731fe8-81b0-4a7f-9785-b214977e30ef"
}

错误码

值	说明
1001	Authentication failed (missing public parameters)
1002	Authentication failed (parameter error)
1003	Authentication failed (invalid signature)
1004	Authentication failed (timestamp expired)
1005	Authentication failed (insufficient authority)
20000	Business Error