# 智能外呼V5

# 业务流程图:

图片

# 1.获取token

接⼝说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤:
    获取token Bearer < accessToken >
    JWT也就是JSON Web Token(JWT),是⽬前最流⾏的跨域身份验证解决⽅案。
  3. 接⼝注意事项
    a. < accessToken >有过期时间,⾃⽣成起 86400秒之后过期。
    b: < accessToken >过期后访问各业务接⼝会返回HTTP 401状态码。
    c: 业务接⼝返回HTTP 401状态码时,需要重新调⽤该接⼝获取< accessToken >。
    d: 调⽤⽅应该在有效期内缓存< accessToken >,禁⽌频繁调⽤该接⼝,避免被封。

请求⽅式:

GET

请求地址:

https://gw.soboten.com/api/6.0.0/tokens

请求参数:

参数 类型 必填 名称 备注
apiKey 字符串 jwt 签发者 登录系统在“设置—接口设置”页面自助开通获取
apiSecret 字符串 jwt 秘钥 登录系统在“设置—接口设置”页面自助开通获取

请求示例:

https://gw.soboten.com/api/6.0.0/tokens?apiKey=xxxxxxxxx&apiSecret=yyyyyyyyyyyyy

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 对象 返回的数据

content对象:

参数 类型 必填 名称 备注
accessToken 字符串 token ⽤于接⼝的调⽤
tokenType 字符串 Bearer 表示验证⽅式 ,固定值
expiresIn 整型 过期时间 ⾃⽣成起xxxx秒之后过期
createTime ⻓整型 token的⽣产时间 毫秒量级时间戳

返回示例:

{ 
  "code": 200, 
  "message": "成功", 
  "content": { 
    "accessToken":"<accessToken>",
    "tokenType":"Bearer", 
    "expiresIn":86400, 
    "createTime": 1635229409745 
  } 
}

# 2.创建任务

接⼝说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤: 通过接⼝的形式,创建拨打电话的任务。

请求⽅式:

POST

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/tasks

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 长度 必填 名称 备注
companyId 字符串 varchar(32) 公司Id 登录系统在“设置—接口设置”页面自助开通获取
taskName 字符串 varchar(20) 任务名称 建议:每个业务每天创建⼀个任务 只能输入中文,英文,数字,以及-_()
templateId 字符串 varchar(32) 话术模板ID
robotNum 整型 int(11) 机器⼈数量
timeType 整型 int(4) 任务有效期类型 ,默认为 2 该字段取值范围:1表示⾃定义, 2表示永久
startTime ⻓整型 bigint(20) 任务有效期起始⽇期, timeType等于1时有效; 毫秒量级时间戳 例如:1577808000000 表示'2020-01- 01 00:00:00'
endTime ⻓整型 bigint(20) 任务有效期结束⽇期, timeType等于1时有效; 毫秒量级时间戳 例如:1580399999000 表示'2020-01- 30 23:59:59'
pushFlag 整型 int(4) 是否开启拨打结果推送 , 默认为 0 该字段取值范围: 0表示未开启, 1表示已开启
pushType 整型 int(4) 推送触发时机 该字段取值范围: 1.转⼈⼯后推送,2. 拨打结束后推送[每次拨打, 不区分拨打结果]
pushUrl 字符串 varchar(255) 推送地址
filterFlag 整型 int(4) 是否开启过滤 ,默认为 0 该字段取值范围: 0表示未开启, 1表示已开启
filterRetryDay 整型 int(11) 过滤天数上限 该字段取值范围: 1,3,7,14;单位: 天
filterRetryNum 整型 int(11) 过滤上限天数内次数上限 该字段取值范围: 1,2,3;单位:次
retryFlag 整型 int(4) 是否开启重拨 ,默认为 0 该字段取值范围: 0表示未开启, 1表示已开启
taskRetryList 对象数组 重播策略数组
numberHide 整型 int(4) 号码隐藏策略 ,默认为 0 该字段取值范围: 0表示不隐藏, 1表示隐藏后四位,2表示隐藏中间四位
priority 整型 int(4) 任务优先级, 优先级⾼则优先拨打。默认为 2 该字段取值范围: 1表示低优先级, 2表示中优先级,3表示⾼优先级
telephoneRule 整型 int(4) 外显规则 ,默认为 1 该字段取值范围: 2.随机,1.轮流
aniList 字符串数组 外显号码
taskCronList 对象数组 拨打时间段数组 默认: [{"begin":"09:00","end":"20:00"}]
usingLocationMatchFlag 整型 int(4) 是否使⽤归属地匹配规则标识 ,默认为 0 该字段取值范围: 0-不使⽤,1-使⽤

taskRetryList对象数组:

该数组中,每个重试策略 retryNum . retryTime 必须相等;

[ 
  { 
    "retryNum":1,
    "retryTime":60, 
    "retryCondition":3 
  }, 
  {
    "retryNum":1, 
    "retryTime":60, 
    "retryCondition":8 
  } 
]
参数 类型 长度 必填 名称 备注
retryNum 整型 int(11) 重拨次数 该字段取值范围: 1,2 单位:次
retryTime 整型 int(11) 重拨间隔 该字段取值范围: 3,15,30,60,90 单位:分钟
retryCondition 整型 int(11) 重拨触发时机 该字段取值范围: 3:⽆⼈接听,4:关机,8:⽤户忙,7:⽤户拒接,5:停机

taskCronList对象数组:

参数 类型 长度 必填 名称 备注
begin 字符串 开始时间 例如:“09:00”
end 字符串 结束时间 例如:“20:00”

请求示例:

{ 
  "templateId":"xxxxxxxxx", 
  "taskName":"新拨打任务", 
  "startTime":1612800000000, 
  "endTime":1613836799999, 
  "robotNum":5, 
  "timeType":"1", 
  "aniList":[ "01022222222", "17111111111" ],
  "telephoneRule":1, 
  "priority":2, 
  "retryFlag":0, 
  "taskRetryList":[ 
    { 
      "retryNum":1, 
      "retryTime":60, 
      "retryCondition":3 
    } 
  ],
  "filterFlag":0, 
  "filterRetryDay":14, 
  "filterRetryNum":1, 
  "taskCronList":[ 
    {
      "begin":"09:00", 
      "end":"20:00" 
    } 
  ],
  "numberHide":"0", 
  "pushFlag":0, 
  "pushType":"", 
  "pushUrl":"" 
}

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 对象 执⾏结果

content对象:

参数 类型 长度 必填 名称 备注
taskId 字符串 varchar(32) 任务的ID
taskName 字符串 varchar(20) 任务的名称
templateId 字符串 varchar(32) 任务拨打的模板Id
templateName 字符串 varchar(255) 任务拨打的模板

返回示例:

{
  "code": 200, 
  "message": "成功", 
  "content": { 
    "taskId": "5f3a8fb33d6d488f9cbe6db0b8082899", 
    "taskName": "新拨打任务", 
    "templateId": "a09114b4cba746f1847ef84d2a5f09a2", 
    "templateName": "新拨打话术模板", 
    "campaignId": "5f3a8fb33d6d488f9cbe6db0b8082899" 
  } 
}

# 3.添加拨打数据

接⼝说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤:
    向活动中添加将要拨打的电话号码,名单数据是通过 http协议消息体 传递的。
    http协议消息体 限制在10M以内。

请求⽅式:

POST

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/tasks/{taskId}/task-contacts

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 长度 必填 名称 备注
companyId 字符串 varchar(32) 公司Id 登录系统在“设置—接口设置”页面自助开通获取
taskId 字符串 varchar(32) 任务Id 创建任务后获得
contactList 对象数组 请求报⽂体的⼤⼩最⼤限制为10M 拨打数据

contactList对象:

⼀条拨打数据,包括三部分内容 对接客户⽅业务Id . ⽤户电话 . ⽤于模板的变量 。

参数 类型 长度 必填 名称 备注
outId 字符串 varchar(120) 数据id 调⽤⽅业务Id
telephone 字符串 varchar(255) ⽤户电话
variable Map<String,String> ⽤于模板的变量 该变量⽤于任务拨打的模板。它是个 Map集合

请求示例:

{ 
  "contactList":[
    { 
      "outId":"outId001", 
      "telephone":"135xxxxxxxx", 
      "variable":{ "话术模板变量KEY":"话术模板变量VALUE" } 
    }
  ] 
}

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 字符串 返回数据

返回示例:

{ 
  "code": 200, 
  "message": "成功", 
  "content": "⼀共传⼊1条数据,成功添加1条数据,0失败" 
}

# 4.查询任务详情

接⼝说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤: 根据指定的任务ID,查看该任务的属性信息。

请求⽅式:

GET

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/tasks/{taskId}

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 必填 名称 备注
companyId 字符串 公司Id 登录系统在“设置—接口设置”页面自助开通获取
taskId 字符串 任务Id

请求示例:

https://gw.soboten.com/api/6.0.0/companies/xxxxxx/tasks/yyyyyy

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 对象 返回数据

content对象:

参数 类型 长度 必填 名称 备注
taskId 字符串 varchar(32) 任务ID
taskName 字符串 varchar(20) 任务名称
templateId 字符串 varchar(32) 拨打模板Id
templateName 字符串 varchar(255) 拨打模板
companyId 字符串 varchar(32) 公司ID
companyName 字符串 varchar(255) 公司
serviceId 字符串 varchar(32) 任务创建者ID
subName 字符串 varchar(255) 任务创建者
taskStatus 整型 int(11) 任务状态 1:空闲,2:排队中,3:拨打时间段外,4: 启动中,5:已启动,6:暂停中,7:已停⽌,8: 已完成,9:已删除,10:已过期
taskCronList 数组 taskCronList 数组
aniList 字符串数组 外显号码
robotNum 整型 int(11) 机器⼈数量
timeType 整型 int(4) 任务有效期类型
startTime ⻓整型 bigint(20) 任务有效期起⽌⽇期
endTime ⻓整型 bigint(20) 任务有效期起⽌⽇期
priority 整型 int(4) 任务拨打优先级
numberHide 整型 int(4) 号码隐藏策略
pushFlag 整型 int(4) 是否开启拨打结果推送
pushType 整型 int(4) 推送触发时机
pushUrl 字符串 varchar(255) 推送地址
createTime ⻓整型 bigint(20) 任务创建时间
retryFlag 整型 int(4) 是否开启重拨
taskRetryList 数组 taskRetryList数组
filterFlag 整型 int(4) 是否开启过滤
filterRetryDay 整型 int(11) 过滤天数上限
filterRetryNum 整型 int(11) 过滤上限天数内次数上限
totalCounts 整型 int(11) 任务内名单总数
executeCounts 整型 int(11) 任务内已拨打的名单数
contactedCounts 整型 int(11) 任务内已拨打且已接通的名单数

返回示例:

{ 
  "code": 200, 
  "message": "成功", 
  "content": { 
    "taskId": "5f3a8fb33d6d488f9cbe6db0b8082899", 
    "taskName": "新外呼任务", 
    "templateId": "a09114b4cba746f1847ef84d2a5f09a2", 
    "templateName": "新外呼话术模板", 
    "campaignId": "5f3a8fb33d6d488f9cbe6db0b8082899", 
    "companyId": "81deba6e4b71492fae865f114454f991", 
    "companyName": "新外呼任务测试账号", 
    "serviceId": "3ff8634129e94cda84397b6ab002171e", 
    "subName": "账号邮箱@qq.com", 
    "taskStatus": 1, 
    "createTime": 1618206356169, 
    "startTime": 1612800000000, 
    "endTime": 1613836799999, 
    "importStatus": 0, 
    "execStartTime": 0, 
    "execEndTime": 0, 
    "robotNum": 5, 
    "timeType": 1, 
    "importTime": 0, 
    "limitCalls": 10, 
    "robotPurchasedNum": 0, 
    "pushUrl": "", 
    "pushType": 0, 
    "pushNum": 0, 
    "priority": 2, 
    "numberHide": 0, 
    "exportStatus": 0, 
    "telephoneRule": 1, 
    "newPushUrlFlag": 0, 
    "retryFlag": 0, 
    "filterFlag": 0, 
    "filterRetryDay": 14, 
    "filterRetryNum": 1, 
    "pushFlag": 0, 
    "executeCounts": 0, 
    "contactedCounts": 0, 
    "totalCounts": 0, 
    "runningRobotCounts": 0, 
    "robotActualAgentsNumber": 0, 
    "startTaskId": "", 
    "startCampaignId": "", 
    "startUserId": "", 
    "startUserName": "", 
    "stopOperatorType": 0, 
    "startOperatorType": 0, 
    "taskCronList": [ 
      { "begin": "09:00", "end": "20:00" } 
    ],
    "aniList": [ "010xxxxxxxx" ],
    "taskRetryList": [], 
    "pushSpace": 0 
  } 
}

# 5.查询拨打数据详情

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤:它⽤来查看指定 outId 的拨打结果; 若想实时获得拨打结果,可以对接<12,拨打结果推送> ;

请求⽅式:

GET

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/tasks/{taskId}/reference-task-contacts/{outId}

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 长度 必填 名称 备注
companyId 字符串 varchar(32) 公司Id 登录系统在“设置—接口设置”页面自助开通获取
taskId 字符串 varchar(32) 任务Id
outId 字符串 调⽤⽅业务Id

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 对象 返回数据

content对象:

参数 类型 必填 名称 备注
detail 对象 拨打数据信息
cdrOut 对象 拨打信息 此处值为拨打结果,如果重拨会被覆盖

detail对象:

参数 类型 长度 必填 名称 备注
contactData Map集合 contactData集合 模板变量
contactId 字符串 varchar(32) 拨打数据ID
intentionCategory 整型 int(11) 意向分类 99:尚未匹配 0:⽆意向,1:A类意向,2:B类意向,3:C类意向, 4:D类意向,5:E类意向
intentionCategoryId 整型 int(11) 意向分类 99:尚未匹配 0:⽆意向,1:A类意 向,2:B类意向,3:C类意向, 4:D类意 向,5:E类意向
templateId 字符串 varchar(32) 拨打模板ID
templateName 字符串 varchar(255) 拨打模板
feeDuration 整型 int(11) 通话时⻓ 单位:秒
dn 字符串 varchar(100) 客户号码
intentionId 字符串 命中的意向ID 命中的意向ID','隔开
intentionName 字符串 命中的意向 命中的意向','隔开
retries 整型 int(11) 重拨次数
status 整型 int(11) 拨打结果 0:未拨打 1:拨打中 2:已接通 3:⽆⼈接听 4:关机 5:停号 6:空号 9:⽤户正忙 10已拦截
userMsgCount 整型 对话交互次数
turnType 整型 是否转⼈⼯ 0:否 1:是
telephone 字符串 执⾏拨打的号码 外显号码
smsSendStatus 整型 是否发送短信 0:未发送 1:发送成功 2:发送失败
startTime ⻓整型 拨打时间 毫秒量级的时间戳

cdrOut对象:

参数 类型 必填 名称 备注
callID 字符串 通话详情ID
dialogList 对象数组 dialog对象数组
recordUrl 字符串 通话录⾳地址 录⾳地址做了防盗链设置,允许空Referer访问
startTime ⻓整型 呼叫开始时间 微秒量级的时间戳
endTime ⻓整型 结束时间 微秒量级的时间戳

contactData集合:

参数 类型 必填 名称 备注
outId 字符串 调⽤⽅的业务ID
其他 字符串

dialog对象:

参数 类型 长度 必填 名称 备注
partyRole 整型 对话参与者 1:表示客户⽅,2:表示机器⼈⽅
content 字符串 说话内容
startTime ⻓整型 毫秒量级的 交互开始时间 时间戳
endTime ⻓整型 毫秒量级的 交互结束时间 时间戳
seq 整型 交互编号

返回示例:

{ 
  "code": 200, 
  "message": "成功", 
  "content": { 
    "detail": { 
      "campaignID": "5f3a8fb33d6d488f9cbe6db0b8082899", 
      "contactData": { 
        "outId": "outId000001", 
        "话术模板变量KEY":"话术模板变量VALUE" },
        "contactId": "383753f83c2f404abf8e02853f035366",
        "intentionCategory": 99, 
        "intentionCategoryId": 99,
        "userMsgCount": 0, 
        "turnType": 0, 
        "smsSendStatus": 0, 
        "startTime": 1627894810552, 
        "feeDuration": 0, 
        "numberHide": null, 
        "telephone": "", 
        "dialedStatus": 0, 
        "strategySearch": 0, 
        "retries": 0, 
        "callID": null, 
        "recordUrl": "", 
        "questions": {}, 
        "companyId": "81deba6e4b71492fae865f114454f991", 
        "taskId": "5f3a8fb33d6d488f9cbe6db0b8082899", 
        "campaignId": "5f3a8fb33d6d488f9cbe6db0b8082899", 
        "callId": null, 
        "taskName": "新外呼任务", 
        "templateId": "a09114b4cba746f1847ef84d2a5f09a2", 
        "templateName": "新外呼话术模板", 
        "status": 0, 
        "intentionName": "--", 
        "intentionId": "99", 
        "dn": "135xxxxxxxx" },
        "cdrOut": { 
          "dialogList":[ 
            {
              "partyRole":2, 
              "content":"我是如来佛祖⽟皇⼤帝观⾳菩萨指定取经使者花果⼭⽔帘洞美猴王⻬天⼤圣孙悟空啊", 
              "startTime":1617957164, 
              "endTime":1617957170, 
              "seq":1, 
              "starMark":1, 
              "remark":"", 
              "nodeName":"新建节点" 
            } 
          ],
          "recordUrl":"https://省略以接⼝返回为准.mp3", 
          "startTime": 1627894810552730, 
          "endTime": 1627894821212740 
        }
      } 
    } 
  }
}

# 6.查询模板

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤:查询智能外呼系统中可⽤的模板,⽤于接⼝创建任务。

请求⽅式:

GET

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/templates

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 必填 名称 备注
companyId 字符串 公司Id 后获得

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 对象数组 返回content对象数组

content对象:

参数 类型 长度 必填 名称 备注
templateId 字符串 varchar(32) 模板id
templateName 字符串 varchar(255) 模板名称
content 字符串 ⾸节点话术
record 字符串 ⾸节点录⾳地址, 多个以英⽂逗号隔开。 录⾳地址做了防盗链设置, 允许空Referer访问

返回示例:

{ 
  "code" : 200, 
  "message" : "成功", 
  "content": [
    { 
      "templateName": "欢迎语模板", 
      "record": "https://省略以接⼝返回为准.mp3", 
      "templateId": "724046a422504457b253eea08778204a", 
      "content": "欢迎" 
    }
  ] 
}

# 7.查询外呼号码资源信息

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤: 略

请求⽅式:

GET

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/numbers

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 必填 名称 备注
companyId 字符串 公司Id 登录系统在“设置—接口设置”页面自助开通获取

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 对象数组 返回content对象数组

content对象:

参数 类型 长度 必填 名称 备注
telephone 字符串 varchar(200) 外显号码
count 整型 int(11) 线路并发数

返回示例:

{ 
  "code": 200, 
  "message": "成功", 
  "content": [ 
    { 
      "telephone": "010xxxxxxxx",
      "count": 10 
    },
    { 
      "telephone": "153xxxxxxxx",
      "count": 10 
    } 
  ] 
}

# 8.查询机器⼈购买数量

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤: 略

请求⽅式:

GET

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/robots/count

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 必填 名称 备注
companyId 字符串 公司Id 登录系统在“设置—接口设置”页面自助开通获取

返回参数:

参数 类型 长度 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 整型 int(11) 购买数量

返回示例:

{
  "code": 200, 
  "message": "成功", 
  "content": 10 
}

# 9.查询指定时间段内任务的拨打量

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤:查询指定时间段内任务的拨打量

请求⽅式:

POST

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/dialing-results/count

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 长度 必填 名称 备注
companyId 字符串 varchar(32) 公司Id 登录系统在“设置—接口设置”页面自助开通获取
beginTime ⻓整型 毫秒量级 开始时间 时间戳
endTime ⻓整型 毫秒量级 结束时间 时间戳
taskIdList 字符串数组 查询的任务ID

请求示例:

{
  "beginTime":1619062903000, 
  "endTime":1619087449000, 
  "taskIdList":["8b816dcc3bbb4ae6828f752aa6a3c638"] 
}

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content dialingCount对象数组 返回数据

dialingCount对象:

参数 类型 必填 名称 备注
taskId 字符串 任务ID
taskName 字符串 任务名称
count ⻓整型 电话拨打量

返回示例:

{
  "code": 200, 
  "message": "成功", 
  "content": [
    { 
      "taskId": "e810971868a344f89f12cce472c2d4ff", 
      "taskName":"拨打任务1", 
      "count": 21 
    },{ 
      "taskId": "649730910efb428e854a256688a88686", 
      "taskName":"拨打任务2", 
      "count": 6 
    },{ 
      "taskId": "9b6cf872fd7942cd8893bee2b08501ca", 
      "taskName":"拨打任务3", 
      "count": 4 
    } 
  ]
}

# 10.指定任务且指定时间段查询任务的拨打详情

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤: ⽤它查询指定任务且指定时间段内的拨打详情

请求⽅式:

POST

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/tasks/{taskId}/dialing-results

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 长度 必填 名称 备注
companyId 字符串 varchar(32) 公司Id 登录系统在“设置—接口设置”页面自助开通获取
taskId 字符串 varchar(32) 任务ID
beginTime ⻓整型 毫秒量级 开始时间 时间戳
endTime ⻓整型 毫秒量级 结束时间 时间戳
pageIndex 整型 分⻚⻚码
pageSize ⻓整型 单⻚⼤⼩ ⼩于等于100

请求示例:

{
  "beginTime":1619062903000, 
  "endTime":1619087449000, 
  "pageIndex":1, 
  "pageSize":5 
}

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content pageInfo对象 返回数据

pageInfo对象:

参数 类型 必填 名称 备注
totalCount 整型 返回总条数
pageNo 整型 ⻚码
pageSize 整型 ⻚⾯⼤⼩ ⼩于等于100
pageCount 整型 总⻚数
list taskContact对象数组 返回数组

taskContact对象:

参数 类型 必填 名称 备注
detail detail对象 拨打的数据信息
cdrOut cdrOut对象 拨打信息 此处值为拨打结果,如果重拨会被覆盖

detail对象:

参数 类型 长度 必填 名称 备注
contactData Map集合 contactData集合 模板变量
contactId 字符串 拨打数据ID
intentionCategory 整型 int(11) 意向分类 99:尚未匹配 0:⽆意向,1:A类意向,2:B类意向,3:C类意向, 4:D类意向,5:E类意向
intentionCategoryId 整型 int(11) 意向分类 99:尚未匹配 0:⽆意向,1:A类意 向,2:B类意向,3:C类意向, 4:D类意 向,5:E类意向
templateId 字符串 varchar(32) 拨打模板ID
templateName 字符串 拨打模板
feeDuration ⻓整型 int(11) 拨打时⻓ 单位:秒
dn 字符串 varchar(255) 客户号码
intentionId 字符串 命中的意向ID 命中的意向ID','隔开
intentionName 字符串 命中的意向 命中的意向','隔开
retries 整型 int(11) 重拨次数
status 整型 int(11) 拨打结果 0:未拨打 1:拨打中 2:已接通 3:⽆⼈接听 4:关机 5:停号 6:空号 9:⽤户正忙 10已拦截
userMsgCount 整型 int(11) 对话交互次数
turnType 整型 int(4) 是否转⼈⼯ 0:未转过 1:转过
telephone 字符串 varchar(255) 执⾏拨打的号码 外显号码
smsSendStatus 整型 int(11) 是否发送短信 0:未发送 1:发送成功 2:发送失败

cdrOut对象:

参数 类型 必填 名称 备注
callID 字符串 通话详情ID
dialogList 对象数组 dialog对象数组
recordUrl 字符串 通话录⾳地址 录⾳地址做了防盗链设置,允许空Referer访问

contactData集合:

参数 类型 长度 必填 名称 备注
outId 字符串 varchar(120) 数据id
其他 字符串

dialog对象:

参数 类型 长度 必填 名称 备注
partyRole 整型 int(11) 对话参与者 1:表示客户⽅,2:表示机器⼈⽅
content 字符串 说话内容
startTime ⻓整型 毫秒量级 交互开始时间 时间戳
endTime ⻓整型 毫秒量级 交互结束时间 时间戳
seq 整型 int(11) 交互编号

返回示例:

{
  "code": 200, 
  "message": "成功", 
  "content": { 
    "totalCount": 20, 
    "pageNo": 1, 
    "pageSize": 1, 
    "pageCount": 20, 
    "list": [ 
      { 
        "detail": { 
          "campaignID": "e810971868a344f89f12cce472c2d4ff", 
          "contactData": { 
            "姓名": "客户⼀", 
            "地址": "", 
            "年龄": "18" 
          },
          "contactId": "318e7ce7e9ba46abb8bcb683c2570dc0", 
          "intentionCategory": 0, 
          "intentionCategoryId": 0,
          "userMsgCount": 1, 
          "turnType": 0, 
          "smsSendStatus": 0, 
          "startTime": 1618731847294, 
          "feeDuration": 9, 
          "numberHide": null, 
          "telephone": "010xxxxxxxx", 
          "dialedStatus": 2, 
          "strategySearch": 0, 
          "retries": 0, 
          "callID": "affdfb16-fbae-4256-9b04-5ab67a9812ad", 
          "recordUrl": "https://oubound-1258560827.cos.ap-beijing.myqcloud.com/dev//20210418/1544/affdfb16-fbae-4256-9b04-5ab67a9812ad.mp3", 
          "questions": {}, 
          "companyId": "81deba6e4b71492fae865f114454f991", 
          "taskId": "e810971868a344f89f12cce472c2d4ff", 
          "campaignId": "e810971868a344f89f12cce472c2d4ff", 
          "callId": "affdfb16-fbae-4256-9b04-5ab67a9812ad", 
          "taskName": "long415701",
          "templateId": "776542bb1f654854bf919b4cd092ce3d", 
          "templateName": "新外呼话术模板", 
          "status": 2, 
          "intentionName": "⽆意向", 
          "intentionId": "99", 
          "dn": "153xxxxxxxx" 
        },
        "cdrOut": { 
          "dialogList": [ 
            { 
              "partyRole": 2, 
              "content": "我是如来佛祖⽟皇⼤帝观⾳菩萨指定取经使者花果⼭⽔帘洞美猴王⻬天⼤圣孙悟空啊", 
              "startTime": 1618731857, 
              "endTime": 1618731863, 
              "seq": 1, 
              "starMark": 0, 
              "remark": "", 
              "nodeName": "欢迎节点"
            },
            {
              "partyRole": 1, 
              "content": "你说什么", 
              "startTime": 0, 
              "endTime": 0, 
              "seq": 2, 
              "starMark": 0, 
              "remark": "", 
              "nodeName": null 
            },
            { 
              "partyRole": 2, 
              "content": "", 
              "startTime": 1618731863, 
              "endTime": 1618731863, 
              "seq": 3, 
              "starMark": 0,
              "remark": "", 
              "nodeName": "欢迎节点" 
            } 
          ],
          "recordUrl": "电话录⾳地址.mp3" 
        } 
      } 
    ] 
  }
}

# 11.操作指定的任务

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤:此接⼝⽤于 暂停任务 . 启动任务 ;

请求⽅式:

Patch

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/tasks/{taskId}/operations

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 必填 名称 备注
companyId 字符串 公司Id 登录系统在“设置—接口设置”页面自助开通获取
taskId 字符串 任务ID
status 整型 开始时间 操作⽬标,该字段取值范围: 1.删除.2.暂停任务.3.启动任务

请求示例:

{"status":2 }

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 字符串

返回示例:

{
  "code": 200, 
  "message": "成功", 
  "content": "" 
}

# 12.拨打结果推送

推送说明:

  1. 接⼝类型:被动推送接⼝
  2. 推送作⽤:可以实时获取拨打结果,在创建任务时设置推送的时机,推送地址

推送⽅式:

POST

推送地址:

创建任务时设置 pushFlag , pushType , pushUrl 。

推送参数:

参数 类型 必填 名称 备注
result 对象 推送结果

推送结果:

参数 类型 必填 名称 备注
data 对象 拨打结果数据
retCode 整型 拨打结果 code 000000 表示成功

拨打结果数据:

参数 类型 必填 名称 备注
msg 数组 对话信息
detail 对象 拨打信息

对话信息:

参数 类型 必填 名称 备注
callID ⻓整型 拨打ID
dateTime ⻓整型 讲话的时间
senderType 整型 对话⽅:1.机器⼈ 0.客户
msg 字符串 讲话内容

拨打信息:

参数 类型 必填 名称 备注
callID 字符串 拨打ID
answerTime ⻓整型 接通时间 微秒量级的时间戳
voiceUrl 字符串 通话录⾳
endTime ⻓整型 结束时间 微秒量级的时间戳
feeDuration 整型 通话时⻓ 从⽤户/机器⼈摘机开始计时,单位:秒
userMsgCount 整型 ⽤户消息数
callDuration 整型 呼叫时⻓ 外呼时:从拨号开始计时,单位:秒
startTime ⻓整型 呼叫开始时间 微秒量级的时间戳
caller 字符串 外显号码
outId 字符串 对接客户⽅的业务ID 通过接⼝导⼊数据时,传⼊
tel 字符串 ⽤户号码
intentionName 字符串 客户意向 命中的意向。若命中多个是以','间隔
status ⻓整型 拨打状态 0:未拨打 1:拨打中 2:已接通 3:⽆⼈接听 4:关机 5:停号 6:空号 7:拒接 9:⽤户正忙
templateId 字符串 任务拨打的模板Id
templateName 字符串 任务拨打的模板
taskId 字符串 任务的ID
taskName 字符串 任务的名称
intentionCategoryId 整型 意向分类 99:尚未匹配 0:⽆意向,1:A类意向,2:B类意向,3:C类意 向, 4:D类意向,5:E类意向

推送参数示例:

{
  "result":{ 
    "data":{ 
      "msg":[ 
        { 
          "callID":"66068cf9-87c2-4ba3-975a-7fa0b9c1005b",
          "msg":"我是如来佛祖⽟皇⼤帝观⾳菩萨指定取经使者花果⼭⽔帘洞美猴王⻬天⼤圣孙悟空啊", "dateTime":1627627002, 
          "senderType":1, 
          "remark":"" 
        } 
      ],
      "detail":{ 
        "callID":"66068cf9-87c2-4ba3-975a-7fa0b9c1005b", 
        "callDuration":44, 
        "answerTime":1627627002772738, 
        "feeDuration":7, 
        "voiceUrl":"对话录⾳地址.mp3", 
        "caller":"010xxxxxxxx", 
        "intentionCategory":"⽆意向", 
        "intentionCategoryId":0,
        "userMsgCount":0, 
        "startTime":1627626965132739, 
        "tel":"136xxxxxxxx", 
        "outId":"zc301434136KG7466ve170520ZN695JMRYvy79", 
        "endTime":1627627009552733, 
        "intentionName":"⽆意向", 
        "status":2, 
        "templateId": "a09114b4cba746f1847ef84d2a5f09a2", 
        "templateName": "新拨打话术模板", 
        "taskId": "5f3a8fb33d6d488f9cbe6db0b8082899", 
        "taskName": "新拨打任务" 
      } 
    },
    "retCode":"000000" 
  } 
}

# 13.修改任务信息

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤: 通过接⼝的形式,修改拨打电话的任务。

请求⽅式:

PUT

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/tasks/{taskId}

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 长度 必填 名称 备注
companyId 字符串 varchar(32) 公司Id 登录系统在“设置—接口设置”页面自助开通获取
taskId 字符串 varchar(32) 任务Id
taskName 字符串 varchar(20) 任务名称
robotNum 整型 机器⼈数量
timeType 整型 任务有效期类型 ,默认为 2 该字段取值范围:1.⾃定义,2.永久
startTime ⻓整型 任务有效期起⽌⽇期
endTime ⻓整型 任务有效期起⽌⽇期
aniList 字符串数组 外显号码
taskCronList 对象数组 拨打时间段数组

taskCronList对象:

参数 类型 必填 名称 备注
begin 字符串 开始时间 例如:“09:00”
end 字符串 结束时间 例如:“20:00”

请求示例:

{ 
  "taskName":"新拨打任务", 
  "startTime":1612800000000, 
  "endTime":1613836799999, 
  "robotNum":5, 
  "timeType":"1", 
  "aniList":[ "010xxxxxxxx", "171xxxxxxxx" ],
  "taskCronList":[ { "begin":"09:00", "end":"20:00" } ] 
}

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 字符串 task对象

返回示例:

{ 
  "code": 200, 
  "message": "成功", 
  "content": "" 
}

# 14.查询全部任务的拨打结果

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤: 通过该接⼝获取指定时间段内整个公司的拨打结果。

请求⽅式:

POST

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/dialing-results

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 长度 必填 名称 备注
companyId 字符串 公司Id 登录系统在“设置—接口设置”页面自助开通获取
pageIndex 整型 int(11) ⻚码
pageSize 整型 int(11) ⻚⾯⼤⼩ ⼩于等于100
beginTime ⻓整型 毫秒量级 开始时间 时间戳
endTime ⻓整型 毫秒量级 结束时间 时间戳
intentionCategory 字符串 意向分类,默认 A 该字段取值范围:A:A类意向,B:B类意向, C:C类意向,D:D类意向,E:E类意向

请求示例:

{ 
  "pageIndex":1, 
  "pageSize":20, 
  "beginTime":1619062903000, 
  "endTime":1619087449000, 
  "intentionCategory":"C" 
}

返回参数:

参⻅ < 10,指定任务且指定时间段查询任务的拨打详情 >

# 15.数据加密传输⽅案

⽅案说明:

满⾜数据加密场景,密钥及demo联系技术⼈员

请求头:

key value 备注
X-Encrypt-Flag * 采⽤加密⽅式传输数据

请求头示例:

X-Encrypt-Flag:*

请求参数:

参数 类型 长度 必填 名称 备注
time 字符串 请求时间戳 毫秒量级时间戳
raw 字符串 加密后的求体参数
hash 字符串 签名

请求时间戳: 客户⽅请求时间与服务⽅的当前时间相差不得超过5秒,若超过视为超时.

请求示例:

{ 
  "time":"1628228461578",
   "raw": "D2tBt0qpsyYCRz1Gnvley28poVChNIs6ETEBMbS+R4kOQUgwR /zqjzjCeJ4JZLmmudR9tsBEhmq0S3v8mngXNojbqrdVtkkvzNy64rCFwCShyFvp7gR6rAMh3/7fOyxH", 
   "hash": "dbc8981e05eba218b95de719388ec928" 
}

返回参数:

参考各接⼝返回值

# 16.查询任务列表

接口说明:

  1. 接⼝类型:主动调⽤接⼝
  2. 接⼝作⽤:

请求⽅式:

POST

请求地址:

https://gw.soboten.com/api/6.0.0/companies/{companyId}/searchtasks

请求头:

key value 备注
Authorization Bearer < accessToken >
Content-type application/json;charset=utf-8

请求参数:

参数 类型 长度 必填 名称 备注
companyId 字符串 varchar(32) 公司Id 后获得
accounts 字符串数组 varchar(255) 账号列表 不填写表示全部
taskStatus 整型 int(11) 任务状态:1:未开始,2:排队中,3: 拨打时间段外, 5:进⾏中,7:已暂停,8:已完结,10:已过期 不填写表示全部
startTimeBegin ⻓整型 毫秒量级 开始时间区间 时间戳,不填写表示全部
startTimeEnd ⻓整型 毫秒量级 开始时间区间 时间戳,不填写表示全部
endTimeStart ⻓整型 毫秒量级 结束时间区间 时间戳,不填写表示全部
endTimeEnd ⻓整型 毫秒量级 结束时间区间 时间戳,不填写表示全部
pageIndex 整型 分⻚⻚码,默认1
pageSize ⻓整型 单⻚⼤⼩,默认100 ⼩于等于100

请求示例:

{
  "pageIndex":1, 
  "pageSize":10, 
  "taskStatus":8, 
  "accounts":["账号邮箱@qq.com"], 
  "startTimeBegin":1637078400000, 
  "startTimeEnd":1637164800000 
}

返回参数:

参数 类型 必填 名称 备注
code 整型 执⾏结果码
message 字符串 执⾏结果
content 对象 返回数据

content对象:

参数 类型 必填 名称 备注
totalCount 整型 返回总条数
pageNo 整型 ⻚码
pageSize 整型 ⻚⾯⼤⼩ ⼩于等于100
pageCount 整型 总⻚数
list 对象数组 返回taskInfo对象数组

taskInfo对象:

参数 类型 长度 必填 名称 备注
taskId 字符串 varchar(32) 任务ID
taskName 字符串 varchar(20) 任务名称
templateId 字符串 varchar(32) 拨打模板Id
templateName 字符串 varchar(255) 拨打模板
serviceId 字符串 varchar(32) 任务创建者ID
subName 字符串 varchar(255) 任务创建者
taskStatus 整型 int(11) 任务状态1:未开始,2:排队中,3:拨打时间段外,4:启动中, 5:进⾏中,6:暂停中,7:已暂停,8:已完结,10:已过期
robotNum 整型 int(11) 机器⼈数量
priority 整型 int(4) 任务拨打优先级
createTime ⻓整型 bigint(20) 任务创建时间
totalCounts 整型 int(11) 任务内名单总数
executeCounts 整型 int(11) 任务内已拨打的名单数
contactedCounts 整型 int(11) 任务内已拨打且已接通的名单数
execStartTime ⻓整型 int(11) 拨打开始时间
execEndTime ⻓整型 int(11) 拨打结束时间
runningRobotCounts 整型 int(11) 正在拨打的机器⼈数

返回示例:

{
  "code": 200, 
  "message": "成功", 
  "content": { 
    "totalCount": 28, 
    "pageNo": 1, 
    "pageSize": 1, 
    "pageCount": 28, 
    "list": [ 
      {
        "taskId": "52e3536dd486439798ef8ad90a9bd12a", 
        "taskName": "新外呼任务", 
        "templateId": "a04eec02471c4cb382fd5f3f1739c861", 
        "templateName": "新外呼话术模板", 
        "taskStatus": 1, 
        "execStartTime": 0, 
        "execEndTime": 0, 
        "priority": 2, 
        "executeCounts": 0, 
        "totalCounts": 0, 
        "runningRobotCounts": 0, 
        "serviceId":"5f3a8fb33d6d488f9cbe6db0b8082899", 
        "subName": "账号邮箱@qq.com", 
        "contactedCounts": 0, 
        "robotNum": 5, 
        "createTime": 1637135495845, 
      } 
    ] 
  }
}

# 17.开放接口demo

下载链接:API Demos

# 18.接⼝状态编码

编码 编码说明
200 成功
500 接⼝内部错误
3240001 创建Consumer时报错,请检查是否已经存在
3240011 创建JWT时报错,请检查是否已经存在
322001 单次导⼊名单不得超过50万
320001 参数为空
320003 任务不存在
320013 签名未通过
320012 未指定任务ID
320011 未指定任务名称
320061 任务名称不能超过20个字
320062 任务名称只能输⼊中⽂,英⽂,数字,以及-_()()
320010 未指定公司ID
320009 未指定话术模板ID
320009 未指定话术模板
320008 未指定名单ID
320000 未指定AppId
320031 未开通Api
320034 未指定App的CustomerId
320038 未指定传输内容
320035 未指定Hash
320039 加密内容Hash不匹配
320036 未指定时间戳
320040 未指定时间戳
320041 指定时间戳超时
320037 未指定Raw
320032 未开通Api
320001 未指定Signature
320002 未指定话术模板名称
320003 未指定任务优先级
320004 未指定任务外显号码
320005 没有指定拨打时间段
320007 没有指定名单数据
320010 没有指定任务有效期类型
320011 没有指定任务有效期时间不正确
320006 没有指定重拨开关
320077 没有指定重拨间隔
320018 没有指定重拨次数
320006 没有指定重拨策略
320012 没有指定重拨条件
320013 没有指定推送开关
320099 没有指定号码归属地匹配开关
320014 没有指定过滤开关
320015 没有指定推送时机
320016 没有指定推送Url
320019 没有指定过滤外呼上限天内限制次数
320020 没有指定过滤外呼上限天内
320021 没有指定号码隐藏策略
320022 没有指定外显规则
320021 没有指定机器⼈数量
320023 没有指定机OutId
320024 未指定AdminId
320026 得不到验证信息
320042 没有指定开始时间
320090 没有指定意向分类错误
320041 没有指定结束时间
320043 指定了错误的开始结束时间
320050 没有指定分⻚⻚码
320051 没有指定单⻚⼤⼩
320052 指定单⻚⼤⼩超限
321060 任务有效期未到!
321000 任务已过期,请创建新任务!
321001 已停⽌
321002 停⽌中
321003 拨打时间段外
321004 未导⼊名单
321005 ⼈为暂停任务
321006 进⾏中的任务不允许删除
321007 未曾导⼊名单
321008 任务已完结
320030 越权访问
320014 该状态下不允许删除任务
320015 该状态下不允许修改任务
320084 该状态下不允许启动任务
320066 任务已在运⾏
320085 正在上传数据不允许修改任务
320017 该状态下不允许停⽌任务
320028 拨打时间段外下停⽌任务
320018 该任务已经在暂停中
320025 该任务已经暂停
320027 该任务已经完成
320033 未指定操作类型
322000 ⽂件超⼤
322001 单次导⼊名单不得超过50万
322002 任务数据导⼊失败
322003 未指定话单ID
322033 未指定拨打数据的ID
322004 任务数据为空
322044 格式错误
322047 删除名单时错误
322051 部分成功
322048 删除名单时超时
323000 任务有效期的类型错误
323001 任务尝试系统时,未获得锁
323002 优先级停⽌时,未找到任务
320029 启动中不许停⽌任务
329001 置为启动中失败
329002 置为停⽌中失败
329083 创建Campaign失败
3290831 创建Campaign超时
329003 该状态下不许暂停
329004 置为完成失败
329007 置为已启动失败
3290071 置为已启动超时
329005 置为拨打时间段外失败
329006 未知的任务状态
329008 置为删除状态失败
3290081 置为删除状态超时
329009 置为过期状态失败
329010 置为排队状态失败
329011 置为停⽌中状态失败
3290111 置为停⽌中状态超时
329012 修改任务信息失败
3290121 修改任务信息超时
329013 暂不修改任务信息
329020 指定机器⼈⼤⼩超限
329021 拨打时间段格式错误
329022 ⼦账号可⽤额度不⾜
320095 没有指定第三⽅PLP开关
320096 没有指定第三⽅PLP地址
322034 删除名单失败
322045 超过条数的限制
322046 超过条数的限制
322047 删除条数为零
322048 修改任务名单超时
322049 修改任务名单失败
322050 部分成功
322053 取消计划任务失败
322054 开始任务失败
322059 没有空闲资源
401 没有登录信息
405 登录信息不符
500 服务器内部错误
501 操作mysql时报错
502 查询ES时报错