呼叫中心接口 - Udesk | 开发者中心

座席外呼

该接口用于发起坐席外呼

请求方法

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

start_time 和 end_time 的格式为：“YYYY-MM-DD hh:mm:ss”，也可省略时间部分：“YYYY-MM-DD”。
start_time 参数必须提供，否则会返回空数据，另外时间获取记录时间跨度限制为30天以下。
该接口的鉴权方法参看鉴权方法。

返回数据

属性名	类型	说明
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

注： curl请求，url里的空格用%20替换

{
    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

请求头

参数名	必填	说明
content_type	是	固定值，application/json

请求参数

参数名	必填	说明
agent_email	是	客服邮箱

注：此接口访问的是open_api_v1部分的接口，需要在请求url中添加鉴权参数，鉴权参照v2的鉴权方法

返回数据

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

示例

curl https://example.udesk.cn/open_api_v1/get_agent_token?email=udesk@admin.com&timestamp=1581111111&nonce=abc1001001001001001001&sign=c1760b7d75c0f1fb6a99f8ad1d0f3864e934f9a53fdcdea1d4aa95da7b58ae6d&sign_version=v2 \
-X POST \
-H 'content-type: application/json' \
-d '{
    "agent_email":"kefu@udesk.cn"
}'

{
    "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分钟
20623	请求仅一次有效, 15分钟内nonce值不能重复	同message	鉴权参数{nonce}在15分钟内已经使用过
20624	open api nonce为空	同message	鉴权参数{nonce}未填写或者为空

status错误码说明

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

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

座席外呼

请求方法

请求参数（Query String）

返回数据

示例

查询客服在线方式

请求方法

请求参数（Query String）

返回数据

示例

设置客服在线方式

请求方法

请求参数（Query String）

返回数据

示例

详解

获取通话记录

请求方法

请求参数（Query String）

返回数据

call_log的数据结构

示例

获取通话记录列表

请求方法

请求参数（Query String）

返回数据

item 元素的数据结构

示例

获取agent_api_token

请求方法

请求头

请求参数

返回数据

示例

code错误码说明

status错误码说明

文档反馈