座席外呼

该接口用于发起坐席外呼

请求方法

POST /open_api/callcenter/agent_callout

请求参数(Query String)

参数名 必填 说明
agent_email 客服邮箱地址
number 外呼号码
timestamp 当前时间戳,格式为"YYYYmmddHHMMSS"

timestamp 与当前时间的误差不能超过5分钟 客服必须处于上线状态, 如果当前是IP话机模式,IP话机必须处于在线状态

该接口的鉴权方法参看鉴权方法,但是 Query String 的顺序必须是 “agent_email + number + timestamp”。

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
call_id 字符串 通话id

示例

curl -X POST https://demo.udesk.cn/open_api/callcenter/agent_callout?agent_email=agent@demo.com&number=13100000001&timestamp=20060102150405&sign=129da7df812jdfsa9912jfdadf81

返回

{
    "code":1000,
    "call_id":"3012@20170513141238282643-z95780414b7bda46-out"
}

查询客服在线方式

该接口用于查询客服在线方式

请求方法

GET /open_api/callcenter/agent_work_way

请求参数(Query String)

参数名 必填 说明
agent_email 客服邮箱地址
timestamp 当前时间戳,格式为"YYYYmmddHHMMSS"

timestamp 与当前时间的误差不能超过5分钟

该接口的鉴权方法参看鉴权方法,但是 Query String 的顺序必须是 “agent_email + timestamp”。

返回数据

属性名 类型 说明
code 整型 执行结果码
1000 代表成功
3003 登录邮箱为空
11011 该员工不存在或已被删除
11008 该员工没有呼叫中心权限
2059 open_api签名不对
2010 无效的客服工作方式(正常工作状态为fixed_voip_online, phone_online)
20621 时间戳格式不对
20622 时间戳误差不能超过5分钟
agent_work_way 字符串 客服在线方式,详见agent_work_way

示例

curl -X GET   'https://demo.udesk.cn/open_api/callcenter/agent_work_way?agent_email=lige@udesk.cn&timestamp=20190702172021&sign=6dd4c035dcc3c43124dfb1edb53db97b'

返回

{
    "code":1000,
    "agent_work_way":"fixed_voip_online"
}

设置客服在线方式

该接口用于设置客服在线方式

请求方法

POST /open_api/callcenter/agent_work_way

请求参数(Query String)

参数名 必填 说明
agent_email 客服邮箱地址
agent_work_way 客服在线方式
timestamp 当前时间戳,格式为"YYYYmmddHHMMSS"

timestamp 与当前时间的误差不能超过5分钟

该接口的鉴权方法参看鉴权方法,但是 Query String 的顺序必须是 “agent_email + agent_work_way + timestamp”。

返回数据

属性名 类型 说明
code 整型 执行结果码
1000 代表成功
3003 登录邮箱为空
11011 该员工不存在或已被删除
11008 该员工没有呼叫中心权限
2059 open_api签名不对
2010 无效的客服工作方式(正常工作状态为fixed_voip_online, phone_online)
20621 时间戳格式不对
20622 时间戳误差不能超过5分钟

示例

curl -X POST 'https://demo.udesk.cn/open_api/callcenter/agent_work_way?agent_email=lige@udesk.cn&agent_work_way=fixed_voip_online&timestamp=20190702184721&sign=8d8fb3d5831a1a8f9972abf6394c9866'

返回

{
    "code":1000
}

详解

参数名 说明
agent_work_way fixed_voip_online IP话机
         phone_online 传统电话(手机/座机)

获取通话记录

该接口用于通过call_id获取通话记录信息

请求方法

GET /open_api/callcenter/call_log

请求参数(Query String)

参数名 必填 说明
call_id 通话记录id
conversation_id 会话id
timestamp 当前时间戳,格式为"YYYYmmddHHMMSS"

timestamp 与当前时间的误差不能超过5分钟 call_id 和 conversation_id 至少传入一个且不可为空,但不能同时传入

该接口的鉴权方法参看鉴权方法,但是 Query String 的顺序必须将timestamp放在最后。如“call_id + timestamp”

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
call_log 对象 通话记录信息

call_log的数据结构

属性名 类型 说明
customer_name 字符串 客户姓名
customer_number 字符串 客户电话
mobile_area 字符串 归属地
call_type 字符串 通话类型,“呼入”或“呼出”
seat_type 字符串 通话方式,“ip座机”或“手机”
result 字符串 通话结果,“接通”、“客户未接通”或“客服未接通”
duration 整型 会话时长
record_url 字符串 通话录音文件地址
satisfic 字符串 满意度评价,“满意”、“不满意”、“未评价”或“无需评价” (仅支持快速路由的默认满意度评价,请尽量使用survey字段)
survey 字符串 满意度评价(新的满意度评价字段,支持智能路由的自定义满意度评价,且兼容快速路由的默认满意度评价)
start_time 日期时间 拨号时间
agent_name 字符串 客服姓名
agent_email 字符串 客服邮箱
ringing_duration 字符串 响铃时间
end_time 日期时间 挂断时间
customer_id 整型 客户id
note_id 整型 业务记录id
trunk_number 字符串 中继号
call_source 字符串 来源
query_type 字符串 排队状态
query_time 整型 排队耗时
leave_message 字符串 留言
drop_side 字符串 通话挂断方
ivr_time 整型 ivr时长
organization_id 字符串 客户所属公司id
has_subsequent_call boolean 后续通话情况(true, false, null)
queue_overflow 字符串 溢出队列
ad_task_name 字符串 自动外呼任务名称
ivr_variables 字符串 ivr变量
defeat_cause 字符串 外呼失败原因(开通后显示)
outline_phone_number 字符串 外线号码
multi_ring_count 整型 顺振次数
tickets 字符串数组 工单编号

示例

curl https://demo.udesk.cn/open_api/callcenter/call_log?call_id=3012@20170513141238282643-z95780414b7bda46-out&timestamp=20060102150405&sign=129da7df812jdfsa9912jfdadf81

返回

{
    "code": 1000,
    "call_log": {
        "customer_name": "测试客户",
        "customer_number": "13100000001",
        "mobile_area": "北京",
        "call_type": "呼出",
        "seat_type": "ip座机",
        "result": "客服未接通",
        "duration": 0,
        "record_url": null,
        "satisfic": "无需评价",
        "survey": "无需评价",
        "start_time": "2006-01-02T15:04:05.000+08:00",
        "agent_name": "测试客服",
        "agent_email": "agent@demo.com",
        "ringing_duration": null,
        "end_time": null,
        "customer_id": 7978,
        "note_id": null,
        "trunk_number": "测试 057126200671",
        "call_source": "队列:乔乔范",
        "query_type": "排队成功",
        "query_time": 0,
        "leave_message": "否",
        "drop_side": "",
        "ivr_time":15,
        "has_subsequent_call":true ,
        "queue_overflow":"负责人;a队列;b队列" ,
        "ad_task_name":"我的自动外呼",
        "ivr_variables": "a:12;b:13",
        "defeat_cause": null,
        "outline_phone_number": "13254110120",
        "multi_ring_count": 10,
        "tickets": ["#123", "#234"]
    }
}

获取通话记录列表

该接口用于一次获取多个通话记录信息

请求方法

GET /api/v2/ucpapp/calllogs

请求参数(Query String)

参数名 必填 说明
start_time 查询开始时间
end_time 查询结束时间
page 页码,从1开始,默认为1
page_size 每页数量,默认30,最大100

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
size 整型 本次返回数量
total 整型 数据总数
total_pages 整形 数据总页数
item 数组 通话记录数组

item 元素的数据结构

属性名 类型 说明
id 整型 唯一标识
note_id 整型 业务记录id
call_start_at 日期时间 通话开始时间
call_type 字符串 通话类型,“呼入”或“呼出”
call_number 字符串 主叫号码
mobile_area 字符串 号码归属地
trunk_number 字符串 中继号
user_name 字符串 客户姓名
user_id 整型 客户id
call_source 字符串 通话来源,“客服: xx”、“队列: xx”、“负责人: xx”、“未选择队列”
queue_type 字符串 排队状态,“排队成功”、“放弃排队”、“排队超时”、“无客服在线”
queue_time 整型 排队时间
agent_id 整型 客服ID
agent_nick_name 字符串 客服姓名
device_info 字符串 设备状态,“ip座机”、“手机”
call_result 字符串 通话结果,“客户未接”、“客户接听”、“客服未接”、“客服拒接”、“客服接听”、“未选择队列”
ring_time 整型 振铃时间
drop_side 字符串 挂断方,“客户”、“客服”
call_time 整型 通话时间
record_url 字符串 录音文件地址
leave_message 字符串 留言
organization_id 字符串 客户所属公司id
satisfaction 字符串 满意度评价,“满意”、“不满意”、“未评价”或“无需评价” (仅支持快速路由的默认满意度评价,请尽量使用survey字段)
survey 字符串 满意度评价(新的满意度评价字段,支持智能路由的自定义满意度评价,且兼容快速路由的默认满意度评价)
ivr_time 整型 ivr时长
has_subsequent_call boolean 后续通话情况(true, false, null)
queue_overflow 字符串 溢出队列
ad_task_name 字符串 自动外呼任务名称
ivr_variables 字符串 ivr变量
defeat_cause 字符串 外呼失败原因(开通后显示)
outline_phone_number 字符串 外线号码
multi_ring_count 整型 顺振次数
tickets 字符串数组 工单编号

示例

curl https://demo.udesk.cn/api/v2/ucpapp/calllogs?start_time=2017-03-02%2012:00:22&end_time=2017-03-12%2012:00:22&page=1&page_size=30&sign=129da7df812jdfsa9912jfdadf81

返回

{
    status: 0,
    message: "成功",
    item:  [
        {
            id: 46,
            note_id: 99,
            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,
            call_source: "队列:xx",
            queue_type: "排队成功",
            queue_time: 4,
            agent_id: 6,
            agent_nick_name: "邢**",
            device_info: "ip座机",
            call_result: "客户接听",
            ring_time: 14,
            drop_side: "客服",
            call_time: 8,
            record_url: "https://www.XXXX.com/fileserver/record/1971j160802?sig=b162b24cab561d24",
            leave_message: "否",
            satisfaction: "无需评价",
            organization_id: 13,
            survey: "无需评价",
            ivr_time: 15,
            has_subsequent_call:null ,
            queue_overflow:"负责人;a队列;b队列" ,
            ad_task_name:"我的自动外呼",
            ivr_variables: "a:12;b:13",
            defeat_cause: null,
            outline_phone_number: "13254110120",
            multi_ring_count: 0,
            tickets: ["#123", "#234"]
        }
    ],
    size: 1,
    total: 1,
    total_pages: 1
}

获取agent_api_token

请求方法

POST /open_api_v1/get_agent_token

请求头

参数名 必填 说明
open_api_token open_api_token,获取方法
content_type 固定值,application/json

请求参数

参数名 必填 说明
email 管理员邮箱
agent_email 客服邮箱
timestamp 当前时间的Unix时间戳
sign 签名,admin_email,openApiToken,当前的时间戳用&拼接,然后用sha1加密后的结果.sha1(adminEmail+"&"+openApiToken+"&"+timestamp)

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
agent_api_token 字符串

示例

curl https://example.udesk.cn/open_api_v1/get_agent_token \
-X POST \
-H 'content-type: application/json' \
-H 'open_api_token: 0d5805e9-1804-4c2f-b8f4-6f9ebb76d24b' \
-d '{
    "email":"admin@udesk.cn",
    "agent_email":"kefu@udesk.cn",
    "timestamp":"1504259426",
    "sign":"96c811c492b0fe4d8051f7e72b91aed17c88e38c"
}'

返回

{
    "code": 1000,
    "agent_api_token": "2557da332258a5d62272d00e3e2e52b5d2a83a2878059e15a2dd107c3e25a8f20a776a402bc8f69431698f49d2dba1bcc794d986453f76218681cc9022bdb717591a5d90"
}

code错误码说明

错误码 message信息 exception:message 描述
2005 没有找到该资源 Couldn't find User with [ WHERE users.company_id = ? AND users.role_id = 2 AND users.email = ? ] 参数错误,未找到数据
2010 无效的客服工作方式(正常工作状态为fixed_voip_online, phone_online) 同message 参数{agent_work_way}的值不在取值范围内
2015 非管理员不可操作 同message 鉴权参数{sign}错误,鉴权未通过
2059 open api签名不对 同message 鉴权参数{sign}错误,鉴权未通过
3003 登录邮箱为空 同message 必填参数{agent_email}未填写
11011 该员工不存在或已被删除 同message 参数{agent_email}错误,未匹配到值
11008 该员工没有呼叫中心权限 同message 参数{agent_email}对应的员工没有呼叫中心权限
20621 时间戳格式不对 同message 必填参数{timestamp}未填写或格式错误
20622 时间戳误差不能超过5分钟 同message 参数{timestamp}与当前时间差超过5分钟

status错误码说明

错误码 message信息 描述
2000 每次最多获取30天的数据 每次获取数据的时间跨度为30天,超过会报此错误信息。如只有参数{start_time},则此参数与当前时间间隔超过了30天
3000 每页最多获取100条通话记录 参数{page_size}的值大于100,超出取值范围
每页获取的数量不能小于1 参数{page_size}的值小于1,超出取值范围