Udesk | 开发者中心

座席外呼

请求方法

url: /open_api/callcenter/agent_callout.json
方式: post

请求参数

agent_email:坐席邮箱 必选项
number:客户电话 必选项
timestamp:时间戳 必选项 如 "20151015123059"
sign:签名值 必选项

请求参数说明

参数名称	类型	值	是否必需	说明
agent_email	String	坐席邮箱	是	外呼坐席邮箱
number	String	客户电话	是	坐席外呼的号码
timestamp	datatime	时间戳	是	当前时间如"20151015123059"
sign	String	加密签名	是	对坐席邮箱，电话号码，时间戳和单点登录共享秘钥进行MD5加密

请求参数规则

1.签名不能为空
2.时间戳不能为空
3.时间戳格式不能错误
4.请求时间误差不能超过5分钟
5.号码必须正确
6.坐席必须上线
7.话机必须上线

以上任一参数验证错误，均会返回未知错误，所以请务必保证参数正确。

请求示例

curl -X POST http://yourdomain.udesk.cn/open_api/callcenter/agent_callout.json -d "agent_email=agent@udesk.cn&number=13000111234&timestamp=20170407153755&sign=7f14c0405a6791c8ce446283080d55c2"

使用postman测试调用的时候，建议使用x-www-form-urlencode形式

返回结果

{
code: 返回结果状态码
call_id: 电话ID
}

sign生成方法

MD5加密("agent_email="+坐席邮箱+"&number="+电话号码+"&timestamp="+时间戳+"&"+ 单点登陆共享秘钥)

如 MD5("agent_email=test@udesk.com&number=13333333333&timestamp=20151015123059&a67904aaf664f4aaac351a5bab9ae043")

通过call_id获取通话记录

请求地址

URL 'open_api/callcenter/call_log.json'
VERB GET

请求参数

call_id     通话id    必传参数
timestamp   时间戳    sign验证需要此参数  如“20151015123059”
sign        签名值    sign验证需要此参数

请求参数说明

参数名称	类型	值	是否必需	说明
call_id	String	通话id	是	通话记录
timestamp	datatime	时间戳	是	当前时间如"20151015123059"
sign	String	加密签名	是	对call_id，时间戳和单点登录共享秘钥进行MD5加密

请求示例

 curl  http://yourdomain.udesk.cn/open_api/callcenter/call_log.json?call_id=3201@siz2938329119&timestamp=20151015123059&sign=b48d4134e7d13839b09b5423e300c352

返回结果

code: 返回结果状态码
call_log: 通话记录
  customer_name:     客户姓名
  customer_number:   客户电话
  mobile_area:       归属地
  call_type:         通话类型
  seat_type:         通话方式
  result:            通话结果
  duration:          会话时长
  record_url:        通话录音
  satisfic:          客户评价
  start_time:        拨号时间戳
  agent_name:        客服姓名
  agent_email:       客服邮箱
  ringing_duration:  响铃时间
  end_time:          挂断时间

返回结果补充说明

参数名称	说明
call_type	通话类型: 呼入,呼出
seat_type	通话方式: ip座机,手机
result	通话结果: 接通, 客服未接通, 客户未接通
satisfic	客户评价: 满意, 不满意, 未评价 ,无需评价

sign生成方法

MD5加密("call_id=" + 通话id + "&timestamp=" + 时间戳 + "&" + 单点登陆共享秘钥)

如 MD5("call_id=fasdvdvdfasdf1232efasdf&timestamp=20151015123059&a67904aaf664f4aaac351a5bab9ae043")

请求呼叫中心通话记录

请求地址

URL '/api/v2/ucpapp/calllogs'
VERB GET
频率限制 1次/2秒

请求参数

start_time:  "2017-03-02 12:00:22", N(非必填) 时间字符串|默认当前开始时间
end_time: "2017-03-12 12:00:22",    N(非必填) 时间字符串|默认当前结束时间
page: 1,                            N(非必填) 页数|默认1页
page_size: 30,                      N(非必填) |默认30条
sign                                Y(必填)

sign加密算法:

按以下参数传递的顺序拼接字符: start_time/end_time/page/page_size sign_str = "start_time=value&end_time=value&page=value&page_size=value"
以上字符串加入 &shared_secret sign_str = sign_str&shared_secret
使用 MD5 计算出签字并小写 Digest::MD5.hexdigest(sign_str).downcase
sign 加密签名，对传递的参数和shared_secret进行MD5加密后的字符串［必填］
shared_secret 公司单点登录秘钥shared_secret [隐藏/计算signature]

sign = MD5加密("start_time=" + 开始时间 + "&end_time=" + "结束时间" + "&page=" + 第几页" + "&page_size=" + 每页数量 + "&" + 单点登录共享秘钥)

如 sign = MD5("start_time=2016-08-01 12:00:00&end_time=2016-08-08 12:00:00&page=1&page_size=30&shared_secret")

请求示例

 curl  http://yourdomain.udesk.cn/api/v2/ucpapp/calllogs?start_time=2017-03-02 12:00:22&end_time=2017-03-12 12:00:22&page=1&page_size=30&sign=75ec4c890d71eedf8dda6c6e926b7fd2

返回结果

{
          status: 0,
          message: "成功",
          item:  [
             {
                  id: 46,                                     //通话记录ID
                  note_id: 99,                                //业务记录ID
                  call_start_at: "2016-08-02 10:23:45",       //通话开始时间
                  call_type: "呼出",                          //通话类型
                  call_number: "134 **** 5615",               //主叫号码
                  mobile_area: "北京",                        //号码归属地
                  trunk_number: "010 **** 7937",              //中继号
                  user_name: "李**",                          //客户名称
                  user_id: 5,                                 //客户ID
                  call_source: "队列：xx",                    //通话来源
                  queue_type: "排队成功",                     //排队状态
                  queue_time: 4,                              //排队时间
                  agent_id: 6,                                //客服ID
                  agent_nick_name: "邢**",                    //客服名称
                  device_info: "ip座机",                      //设备状态
                  call_result: "客户接听",                    //通话结果
                  ring_time: 14,                              //振铃时间
                  drop_side: "客服",                          //挂断方
                  call_time: 8,                               //通话时间
                  record_url: "http://www.XXXX.com/fileserver/record/1971jiau1iahucd173929b281177c_1470104625411014_20160802?sig=bb3df793042290780162b24cab561d24", //录音地址
                  leave_message: "否",                        //留言
                  satisfaction: "无需评价"                    //满意度评价
            }
        ],
          size: 1,                                            //当前页记录数
          total: 1,                                           //总记录数
          total_pages: 1                                      //总页数
}

返回结果补充说明

参数名称	说明
call_type	通话类型: 呼入,呼出
call_source	通话来源: 客服: xx, 队列: xx, 负责人: xx,未选择队列
queue_type	排队状态: 排队成功, 放弃排队, 排队超时, 无客服在线
device_info	设备状态: ip座机,手机
call_result	通话结果: 客户未接, 客户接听, 客服未接, 客服拒接, 客服接听, 未选择队列
drop_side	挂断方: 客户, 客服
satisfaction	客户评价: 满意, 不满意, 未评价 ,无需评价

开放api说明文档

接口调用频次限制皆为1次/秒
调用要求 只能在服务端调用，禁止在客户端调用
关于自定义字段的说明和使用方式请参见自定义字段说明
所有的接口调用之前请鉴权，鉴权方式参考“鉴权说明.md”

鉴权方法

除了获取api_token接口之外，其他接口皆需鉴权。 1. 获取open_api_token - 详见“登录接口”文档 2. 计算签名 + 需要三个参数 1. email 管理员的email地址 2. timestamp 从1970年1月1日（UTC/GMT的午夜）开始所经过的秒数，即UNIX时间戳 3. open_api_token 公司api_token + 待签名字符串 sign_str = email&open_api_token&timestamp + 签名 sign = Digest::SHA1.hexdigest(sign_str) 3. 鉴权 + 请求时在URL的参数中加上email和timestamp和sign

签名及请求示例

#签名示例
email = "admin@udesk.cn"
timestamp = "1488337316"
open_api_token = "6523c055-a6b7-4254-8e46-cd8ee80d6ce0"
sign_str = email + "&" + open_api_token + "&" + timestamp
#sign_str = "admin@udesk.cn&6523c055-a6b7-4254-8e46-cd8ee80d6ce0&1488337316"
sign = Digest::SHA1.hexdigest(sign_str)
#sign = "979ef4b81415da8157d31f0c2d76852f51847107"

#请求示例
curl -X GET "http://reocar.udesk.cn/open_api_v1/agents?email=admin@udesk.cn&p###word=p###word&timestamp=1488337316&sign=979ef4b81415da8157d31f0c2d76852f51847107"

//返回结果示例
{"code":1000,"agents":[{"id":3,"email":"agent2@udesk.cn","nick_name":"Jerry","profile":"im","aliase":null,"cellphone":null,"role_name":"agent","duty":null,"user_group_ids":[],"im_ability_value":1},{"id":2,"email":"agent@udesk.cn","nick_name":"Tom","profile":"im","aliase":null,"cellphone":null,"role_name":"agent","duty":null,"user_group_ids":[],"im_ability_value":3}],"meta":{"current_page":1,"total_pages":1,"count":2}}

新建外呼任务

请求地址

URL: 'https://yourdomain.udesk.cn/open_api_v1/callout_tasks/'
METHOD: POST

请求参数说明

callout_task:
  name: 名字
  description: 描述
  start_at: 开始时间
  end_at: 结束时间
  description: 描述
  status: 状态，0为暂停，1为开启
  task_type: 只能传0，为预览式外呼
  agent_type: 坐席，0为全部客服，1为队列，2为自定义，不可以传1
  customers: 客户列表，为数组，可以传id, token, 电话，邮箱。
  agent_ids: 当agent_type为客服时传入，客服id，数组

注：客户列表参数为一个数组，数组中的每个元素要这么填：

[{"type":"id","cotent":123}, {"type":"token","cotent":"123456"},{"type":"email","cotent":"xyz@ema.com"},{"type":"cellphone","cotent":"13244445555"}]

请求示例

{
  "callout_task":
    {
      "name":"CallOutTask",
      "description":"waihu",
      "agent_type":2,
      "agent_ids":[5],
      "task_type":0,
      "status":1,
      "start_at":"2017-03-03",
      "end_at":"2017-04-05",
      "customers":[{"type":"token", "content":"123456"},{"type":"id","content":107387},{"type":"email","content":"wxb1@qq.com"}
      ,{"type":"cellphone","content":"13500010846"}]
    },
    "email":"admin@ucpapp.udesk.cn",
    "timestamp":"1490247563",
    "sign":"449401ba3c4ad7107c07f6ca9bfa922b71241a1f"
}

返回参数说明

code: 结果状态码
callout_task: 外呼任务
  id: id
  name: 名字
  description: 描述
  start_at: 开始时间
  end_at: 结束时间
  description: 描述
  created_at: 创建时间
  status: 状态，0为暂停，1为开启
  task_type: 只能传1，为预览式外呼
  agent_type: 坐席，0为全部客服，1为队列，2为自定义
  queue_ids: 队列id，数组
  customer_ids: 客户id，数组
  agent_ids: 客服id，数组
  customer_count: 客户数量
  executed_count: 接通数量
  success_count: 成功数量
  total_executed_count: 总执行数量
  total_success_count: 总接通数量

返回示例

{
  "code": 1000,
  "callout_task": {
    "id": 15,
    "name": "CallOutTask",
    "status": "0",
    "description": "waihu",
    "created_at": "2017-03-14T14:12:42.000+08:00",
    "customer_ids": [
      200,
      201,
      3,
      700
    ],
    "agent_ids": [
      4,
      9
    ],
    "start_at": "2017-03-03T00:00:00.000+08:00",
    "end_at": "2017-04-05T23:59:00.000+08:00",
    "task_type": 0,
    "agent_type": 0,
    "queue_ids": null,
    "customer_count": 4,
    "executed_count": 0,
    "success_count": 0,
    "total_executed_count": 0,
    "total_success_count": 0
  }
}

查看外呼任务

请求地址

URL: 'https://yourdomain.udesk.cn/open_api_v1/callout_tasks/:id'
METHOD: GET

请求参数说明

id: 外呼任务id

请求示例

##get请求没有json
https://tianya.udesk.cn/open_api_v1/callout_tasks/17?email=admin@ucpapp.udesk.cn&timestamp=2017-02-06&sign=449401ba3c4ad7107c07f6ca9bfa922b71241a1f

返回参数说明

code: 结果状态码
callout_task: 外呼任务
  id: id
  name: 名字
  description: 描述
  start_at: 开始时间
  end_at: 结束时间
  description: 描述
  created_at: 创建时间
  status: 状态，0为暂停，1为开启
  task_type: 只能传1，为预览式外呼
  agent_type: 坐席，0为全部客服，1为队列，2为自定义
  queue_ids: 队列id，数组
  customer_ids: 客户id，数组
  agent_ids: 客服id，数组
  customer_count: 客户数量
  executed_count: 接通数量
  success_count: 成功数量
  total_executed_count: 总执行数量
  total_success_count: 总接通数量

返回示例

{
  "code": 1000,
  "callout_task": {
    "id": 15,
    "name": "CallOutTask",
    "status": "0",
    "description": "waihu",
    "created_at": "2017-03-14T14:12:42.000+08:00",
    "customer_ids": [
      200,
      201,
      3,
      700
    ],
    "agent_ids": [
      4,
      9
    ],
    "start_at": "2017-03-03T00:00:00.000+08:00",
    "end_at": "2017-04-05T23:59:00.000+08:00",
    "task_type": 0,
    "agent_type": 0,
    "queue_ids": null,
    "customer_count": 4,
    "executed_count": 0,
    "success_count": 0,
    "total_executed_count": 0,
    "total_success_count": 0
  }
}

编辑外呼任务

请求地址

URL: 'https://yourdomain.udesk.cn/open_api_v1/callout_tasks/:id'
METHOD: PUT

请求参数说明

callout_task: 外呼任务
  name: 名字
  description: 描述
  start_at: 开始时间
  end_at: 结束时间
  description: 描述
  status: 状态，0为暂停，1为开启
  task_type: 只能传1，为预览式外呼
  customers: 客户列表，为数组，可以传id, token, 电话，邮箱。

请求示例

//请注意，id放在url里，这是restful风格的路由
{
  "callout_task":
    {
      "name":"CallOutTask",
      "description":"waihu",
      "status":1,
      "start_at":"2017-03-03",
      "end_at":"2017-04-05",
      "customers":[{"type":"token", "content":"123456"},{"type":"id","content":107387},{"type":"email","content":"wxb1@qq.com"},{"type":"cellphone","content":"13500010846"}]
    },
    "email":"admin@ucpapp.udesk.cn",
    "timestamp":"2017-02-06",
    "sign":"449401ba3c4ad7107c07f6ca9bfa922b71241a1f"
}

返回参数说明

code: 结果状态码
callout_task: 外呼任务
  id: id
  name: 名字
  description: 描述
  start_at: 开始时间
  end_at: 结束时间
  description: 描述
  created_at: 创建时间
  status: 状态，0为暂停，1为开启
  task_type: 只能传1，为预览式外呼
  agent_type: 坐席，0为全部客服，1为队列，2为自定义
  queue_ids: 队列id，数组
  customer_ids: 客户id，数组
  agent_ids: 客服id，数组
  customer_count: 客户数量
  executed_count: 接通数量
  success_count: 成功数量
  total_executed_count: 总执行数量
  total_success_count: 总接通数量

返回示例

{
  "code": 1000,
  "callout_task": {
    "id": 15,
    "name": "CallOutTask",
    "status": "0",
    "description": "waihu",
    "created_at": "2017-03-14T14:12:42.000+08:00",
    "customer_ids": [
      200,
      201,
      3,
      700
    ],
    "agent_ids": [
      4,
      9
    ],
    "start_at": "2017-03-03T00:00:00.000+08:00",
    "end_at": "2017-04-05T23:59:00.000+08:00",
    "task_type": 0,
    "agent_type": 0,
    "queue_ids": null,
    "customer_count": 4,
    "executed_count": 0,
    "success_count": 0,
    "total_executed_count": 0,
    "total_success_count": 0
  }
}

删除外呼任务

请求地址

URL: 'https://yourdomain.udesk.cn/open_api_v1/callout_tasks/:id'
METHOD: DELETE

请求参数

id: 外呼任务id

请求示例

{
  "id": 1,
  "email":"admin@ucpapp.udesk.cn",
  "timestamp":"2017-02-06",
  "sign":"449401ba3c4ad7107c07f6ca9bfa922b71241a1f"
}

返回参数说明

code: 结果状态码
id: 外呼任务id

返回结果示例

{ "code": 1000,"id":11 }

外呼任务-客户列表

该接口返回指定外呼任务的客户列表

请求地址

URL: 'https://yourdomain.udesk.cn/open_api_v1/callout_tasks/customers'
METHOD: GET

请求参数说明

id: 外呼任务id
page: 分页参数，请求哪一页，默认为1
per_page: 每页数量，默认为10

请求参数示例

https://tianya.udesk.cn/open_api_v1/callout_tasks/customers?email=admin@ucpapp.udesk.cn&timestamp=2017-02-06&sign=449401ba3c4ad7107c07f6ca9bfa922b71241a1f&id=40&page=1&per_page=5

返回结果说明

code: 结果状态码
customers: 客户列表
  task_id: 客户外呼任务id
  id: 客户id
  nick_name: 昵称
  cellphones: 客户手机列表
    content: 号码
    id: 手机号id
  agent_id: 客服id
  call_count: 通话数量
  result: 通话结果
meta: 分页信息
  current_page: 当前页数
  total_pages: 总页数
  total_count: 总数量

返回结果示例

{
  "code": 1000,
  "customers": [
    {
      "task_id": 40,
      "id": 200,
      "nick_name": "亚历山大",
      "cellphones": [],
      "agent_id": 4,
      "call_count": 0,
      "result": null
    },
    {
      "task_id": 41,
      "id": 201,
      "nick_name": "亚历山大",
      "cellphones": [],
      "agent_id": 9,
      "call_count": 0,
      "result": null
    },
    {
      "task_id": 42,
      "id": 3,
      "nick_name": "大大1w",
      "cellphones": [
        {
          "id": 5,
          "content": "123333311111"
        }
      ],
      "agent_id": 4,
      "call_count": 0,
      "result": null
    },
    {
      "task_id": 43,
      "id": 700,
      "nick_name": "亚历山大",
      "cellphones": [],
      "agent_id": 9,
      "call_count": 0,
      "result": null
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 4
  }
}

外呼任务-客服列表

该接口返回指定外呼任务的客服列表

请求地址

URL: 'https://yourdomain.udesk.cn/open_api_v1/callout_tasks/agents'
METHOD: GET

请求参数说明

id: 外呼任务id
page: 分页参数，请求哪一页，默认为1
per_page: 每页数量，默认为10

请求参数示例

https://ucpapp.udesk.cn/open_api_v1/callout_tasks/customers?email=admin@ucpapp.udesk.cn&timestamp=2017-02-06&sign=449401ba3c4ad7107c07f6ca9bfa922b71241a1f&id=40&page=1&per_page=5

返回参数说明

code: 结果状态码
agents: 客服
  customer_count: 客户数量
  executed_count: 执行数量
  total_success_count: 成功数量
  total_executed_count: 总执行数量
  id: 客服id
  name: 客服名字
meta: 分页信息
  current_page: 当前页
  total_pages: 总页数
  total_count: 总数量

返回参数示例

{
  "code": 1000,
  "agents": [
    {
      "customer_count": 2,
      "executed_count": 0,
      "success_count": 0,
      "total_executed_count": 0,
      "total_success_count": 0,
      "id": 4,
      "name": "大大啊"
    },
    {
      "customer_count": 2,
      "executed_count": 0,
      "success_count": 0,
      "total_executed_count": 0,
      "total_success_count": 0,
      "id": 9,
      "name": "dada"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 2
  }
}

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

座席外呼

请求方法

请求参数

请求参数说明

请求参数规则

请求示例

返回结果

sign生成方法

通过call_id获取通话记录

请求地址

请求参数

请求参数说明

请求示例

返回结果

返回结果补充说明

sign生成方法

请求呼叫中心通话记录

请求地址

请求参数

sign加密算法:

请求示例

返回结果

返回结果补充说明

开放api说明文档

鉴权方法

签名及请求示例

新建外呼任务

请求地址

请求参数说明

请求示例

返回参数说明

返回示例

查看外呼任务

请求地址

请求参数说明

请求示例

返回参数说明

返回示例

编辑外呼任务

请求地址

请求参数说明

请求示例

返回参数说明

返回示例

删除外呼任务

请求地址

请求参数

请求示例

返回参数说明

返回结果示例

外呼任务-客户列表

请求地址

请求参数说明

请求参数示例

返回结果说明

返回结果示例

外呼任务-客服列表

请求地址

请求参数说明

请求参数示例

返回参数说明

返回参数示例

文档反馈