概要
事件回调，又称 Webhook，是指当特定事件发生时，Udesk 将特定的数据以固定的格式发送给您指定的回调地址。
Udesk 的事件回调支持以下事件：
| 事件名 | 说明 |
|---|---|
| Customer_create | 新建客户时 |
| Customer_update | 修改客户时 |
| Customer_destroy | 删除客户时 |
| Organization_create | 新建客户公司时 |
| Organization_update | 修改客户公司时 |
| Organization_destroy | 删除客户公司时 |
| ImSubSession_create | IM 会话新建时 |
| ImSubSession_close | IM 会话关闭时 |
| ShutQueue_create | IM 放弃排队时 |
| AgentNote_update | IM 会话结束/CC 通话结束后业务记录修改时 |
| ImSurveyVote_create | 对话满意度保存时 |
如果需要使用 Udesk 事件回调功能，您要执行以下步骤：
- 编写代码，实现事件回调处理接口，并提供事件回调地址；
- 调用设置事件回调地址接口，将您实现的事件回调处理接口地址设置事件回调地址；
- 调用设置事件回调类型接口，根据您的需要设置需要接收哪些事件回调;
- 调用设置事件回调的 content_type 接口，根据您的需要设置 content_type 的值;
编写事件回调处理接口
该接口需要由您实现，并且满足特定的要求。
Udesk 会使用 POST 方法请求您提供的回调地址，并将数据作为请求体（Request Body）传送。
请求体的数据结构如下：
| 属性 | 类型 | 说明 |
|---|---|---|
| action | 字符串 | 事件类型 |
| message | 对象 | 事件数据 |
不同事件 message 所有不同。
Customer_create 事件
“message”的数据结构参考客户数据
示例：
{
"action": "Customer_create",
"message": {
"id": 1,
"nick_name": "测试用户",
"level": "normal",
"description": null,
"owner_id": 1,
"owner_group_id": 1,
"custom_fields": {
"SelectField_1": ["0"],
"SelectField_2": ["0"]
},
"open_api_token": null,
"organization_id": null,
"is_blocked": false,
"tags": [],
"email": "customer@sample.com",
"other_emails": [],
"cellphones": [
{
"id": 1,
"content": "13000000001"
}
],
"platform": "手工录入"
}
}
Customer_update 事件
“message”的数据结构如下：
{
"id": 客户id,
"changes": {
"属性名": [原值, 变更后的值]
}
}
其中“属性名”参看客户数据
示例：
{
"action": "Customer_update",
"message": {
"id": 1,
"changes": {
"nick_name": ["测试客户1", "测试客户2"],
"owner_id": [1, 2]
}
}
}
Customer_destroy 事件
“message”的数据结构如下：
{
"id": 被删除的客户id
}
示例
{
"action": "Customer_destroy",
"message": {
"id": 1
}
}
Organization_create 事件
“message”的数据结构参考客户公司数据
示例：
{
"action": "Organization_create",
"message": {
"id": 1,
"name": "测试公司1",
"domains": "https://www.test1.com",
"custom_fields": {
"TextField_1": "测试文本",
"SelectField_1": ["0"]
},
"description": "该公司仅用来举例"
}
}
Organization_update 事件
“message”的数据结构如下：
{
"id": 客户公司id,
"changes": {
"属性名": [原值, 变更后的值]
}
}
其中“属性名”参看客户公司数据
示例：
{
"action": "Organization_update",
"message": {
"id": 1,
"changes": {
"name": ["测试公司1", "测试公司2"]
}
}
}
Organization_destroy 事件
“message”的数据结构如下：
{
"id": 被删除的客户公司id
}
示例
{
"action": "Organization_destroy",
"message": {
"id": 1
}
}
ImSubSession_create 事件
“message”的数据结构如下
{
"id": 新创建的会话id,
"im_sub_session_log": 对话记录详情
}
示例
{
"action": "ImSubSession_create",
"message": {
"id": 14980761,
"im_sub_session_log": [
{
"session_id": 8761,
"sub_session_id": 14980761,
"agent_id": 862,
"customer_id": 117092,
"platform": "微信",
"source": "微信-xx",
"weifeng": "weifeng_params",
"created_at": "2017-10-27 21:23:45"
}
]
}
}
ImSubSession_close 事件
“message”的数据结构如下
{
"id": 被关闭的会话id,
"im_sub_session_log": 对话记录详情,
"im_log_infos": 聊天记录
}
示例
{
"action": "ImSubSession_close",
"message": {
"id": 14980761,
"im_sub_session_log": [
{
"session_id": 8761,
"sub_session_id": 14980761,
"note_id": 6541,
"note_content": "业务记录主题",
"note_custom_fields": {
"TextField_1":"sdfaf",
"TextField_2":"2016-09-01",
"TextField_3":"00:00:02",
"TextField_4":"23",
"TextField_5":"24",
"SelectField_1":"0",
"TextField_7":"cessf沙阿发二娃分",
"SelectField_2":"0,0",
"SelectField_3":"2",
"SelectField_4":"0,1,2,3,4"
},
"note_template_id": "业务记录模版id",
"note_template_name": "业务记录模版名称",
"customer_id": 117092,
"customer_name": "xx",
"customer_custom_fields": {},
"agent_id": 862,
"agent_nick_name": "xx_客服",
"agent_email": "agent@udesk.cn",
"created_at": "2017-10-27 21:23:45",
"closed_at": "2017-10-27 21:23:59",
"resp_seconds": null,
"queue_seconds": "未排队",
"sustain_seconds": 14,
"survey_vote_id": null,
"platform": "微信",
"belong_queue": "queue_company_6_group_271",
"agent_msg_num": 1,
"customer_msg_num": 1,
"source": "微信-xx",
"source_url": null,
"queue_start_time": "2017-10-27 21:23:45",
"conversations_num_today": 3,
"agent_invite_vote_count": null,
"search_keyword": null,
"custom_channel": null,
"last_response": "agent",
"alert_num": 1,
"alert_desc": "敏感词1次,响应超时,会话超时",
"ticket_num": 2,
"ticket_nos": "#140,#141",
"ticket_ids": [342342,24234],
"im_web_plugin_id": 1,
"sender": "customer",
"active_guest": "agent",
"weifeng": "weifeng_params",
"close_method": "agent_close",
"robot_session_id": 4303299,
"resolved_state": "0",
"curl_url": "https://demo.udesk.cn/im_client/?web_plugin_id=1",
"customer_tags": ["客户标签1", "客户标签2", "客户标签3"],
"weixin_info": {
"name": "xx"
}
}
],
"im_log_infos": [
{
"id": 70161,
"created_at": "2017-10-27 21:23:54",
"sender": "customer",
"user_id": 117092,
"content": "{"type":"image","platform":"wechat","data":{"content":"https://dn-udeskim.qbox.me/022c4a12-4f83-492d-8e4d-5f04191e0058.jpg","duration":null,"origin_url":"https://api.weixin.qq.com/cgi-bin/media/get?access_token=Z7kg69qvIqh_5-jZmzmKVgbt3mXP4pvmiNpqt_risTXuF1tOGw2bax9YaSVVQM4PR0HH_q7Fpou3PlYJhujH09xJxQyNmIhGYank_vmMxnEPTJfAHAWAQ&media_id=ObkKKAP5qS8wtFgXi1C2VMHKCZxQxxSvg1YVH2uHuDB_1HfORtcRf_3L2FmCUvO6"}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": ""
},
{
"id": 70158,
"created_at": "2017-10-27 21:23:45",
"sender": "agent",
"user_id": 862,
"content": "{"type":"rich","platform":"wechat","data":{"content":"<p>客服xx_客服_昵称为您服务</p><p>啦啦啦啦啦-英语</p>","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": ""
},
{
"id": 70157,
"created_at": "2017-10-27 21:23:45",
"sender": "customer",
"user_id": 117092,
"content": "{"type":"message","platform":"wechat","data":{"content":"有新的咨询进来了。","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": ""
},
{
"id": 70159,
"created_at": "2017-10-27 21:23:48",
"sender": "agent",
"user_id": 862,
"content": "{"type":"message","platform":"wechat","data":{"content":"你好微信","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": "arrive"
},
{
"id": 70160,
"created_at": "2017-10-27 21:23:52",
"sender": "agent",
"user_id": 862,
"content": "{"type":"message","platform":"wechat","data":{"content":"普通","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": "arrive"
}
{
"id": 70161,
"created_at": "2017-10-27 21:23:59",
"sender": "agent",
"user_id": 862,
"content": "{"type":"close","platform":"wechat","data":{"content":"xx_客服关闭对话","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": "arrive"
}
]
}
}
备注：
1、对话结束方式-close_method:
"agent_close" | 客服关闭
"redirect_close" | 转接关闭
"sys_close" | 系统关闭
"customer_close" | 客户关闭
2、消息发送状态-send_status:
"sending" | 发送中
"arrive" | 已送达
"fail" | 发送失败
"off_sending" | 离线发送
"off_arrive" | 离线送达
"rollback" | 已撤回
3、机器人会话ID-robot_session_id:
客服系统侧机器人会话ID
4、满意度-是否已解决-resolved_state:
"0" | 已解决
"1" | 未解决
ShutQueue_create 事件
“message”的数据结构如下：
{
"id": 记录ID
"customer_id": 客户ID,
"nick_name": 客户姓名,
"queue_name": 排队队列名称,
"queue_type": 队列类型,
"queue_id": 排队队列员工组ID、员工ID,
"queue_start_time": 开始排队时间,
"queue_end_time": 结束排队时间,
"queue_seconds": 排队时长,
"chanel": 渠道,
"im_web_plugin_id": 来源插件ID,
"menu_names": 导航菜单名称
}
示例
{
"action": "ShutQueue_create",
"message": {
"id": "1",
"customer_id": "46",
"nick_name": "北京cloud-ark.cn联通(1535800080)",
"queue_name": "排队客服名称",
"queue_type": "agent",
"queue_id": "33",
"queue_start_time": "2018-09-01 19:08:00 +0800",
"queue_end_time": "2018-09-01 19:08:30 +0800",
"queue_seconds": "30秒",
"chanel": "web",
"im_web_plugin_id": 1,
"menu_names": "导航菜单名称"
}
}
备注：
当排队队列为客服时，queue_name是客服名称，queue_type是“agent”，queue_id是客服id
当排队队列为客服组时，queue_name是客服组名称，queue_type是“group”，queue_id是客服组id
当排队队列为公司时，queue_name是“公司”，queue_type是“company”，queue_id是“公司“
AgentNote_update 事件
“message”的数据结构如下：
如果是 IM 对话的业务记录修改,数据结构如下:
{
"updated_at": 修改时间，精确到秒,
"sub_session_id": 对话ID,
"note_id": 业务记录ID,
"note_content": 业务记录主题,
"field_id": 字段ID,
"field_title": 字段name,
"filed_value": 修改后的字段value
}
如果是 CC 通话的业务记录修改,数据结构如下:
{
"updated_at": 修改时间，精确到秒,
"conversation_id": 通话记录id,
"note_id": 业务记录ID,
"note_content": 业务记录主题,
"field_id": 字段ID,
"field_title": 字段name,
"filed_value": 修改后的字段value
}
示例(IM)
{
"action": "AgentNote_update",
"message": {
"updated_at": "2019-12-06 10:02:40",
"sub_session_id": 4947,
"note_id": 292,
"note_content": "业务记录主题",
"field_id": "SelectField_98",
"field_title": "投诉类型",
"filed_value": "0"
}
}
示例(CC)
{
"action": "AgentNote_update",
"message": {
"updated_at": "2019-12-06 10:02:40",
"conversation_id": 4947,
"note_id": 292,
"note_content": "业务记录主题",
"field_id": "SelectField_98",
"field_title": "投诉类型",
"filed_value": "0"
}
}
备注:
1. 只有在对话关闭后的业务记录修改，保存后即推送该业务记录的修改信息
2. 通过API方式修改业务记录不触发事件回调
ImSurveyVote_create 事件
“message”的数据结构如下：
{
"created_at": 保存时间，精确到秒,
"sub_session_id": 对话ID,
"option_id": 满意度选项ID,
"option_name": 满意度选项name,
"tags": 满意度标签name,
"remark": 备注的value
}
示例
{
"action": "ImSurveyVote_create",
"message": {
"created_at": "2019-12-06 10:13:04",
"sub_session_id": 4947,
"option_id": 1234,
"option_name": "非常满意",
"tags": "标签1,标签2",
"remark": "备注"
}
}
设置事件回调地址接口
该接口用于设置事件回调地址 鉴权：参看鉴权方法
请求方法
POST /set_url
请求参数（Request Body）
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| push_url | 是 | 字符串 | 事件回调地址 |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000 代表成功 |
| push_url | 字符串 | 修改后的事件回调地址 |
示例
curl https://demo.udesk.cn/open_api_v1/set_url?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X POST \
-H 'content-type: application/json' \
-d '
{
"push_url": "https://www.demo.com/push_url"
}'
返回
{
"code": 1000,
"push_url": "https://www.demo.com/push_url"
}
设置事件回调的 content_type 接口
该接口用于设置事件回调地址 鉴权：参看鉴权方法
请求方法
POST /set_push_content_type
请求参数（Request Body）
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| push_content_type | 是 | 字符串 | 事件回调请求的 content_type |
- 注意：push_content_type 可传入 JSON,对应的返回值是 json 字符串，默认为"application/x-www-form-urlencoded"
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000 代表成功 |
| webhook_push_type | 字符串 | 回调返回值的结构 |
示例
curl https://demo.udesk.cn/open_api_v1/set_push_content_type?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X POST \
-H 'content-type: application/json' \
-d '
{
"push_content_type": "JSON"
}'
返回
{
"code": 1000,
"webhook_push_type": "JSON"
}
设置事件回调类型接口
该接口用于设置需要接收哪些事件回调 鉴权：参看鉴权方法
请求方法
POST /set_permissions
请求参数（Request Body）
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| permissions | 是 | 对象 | 设置集合 |
permissions 的数据结构
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| customer_create | 否 | 布尔 | 是否接收客户创建事件 |
| customer_update | 否 | 布尔 | 是否接收客户修改事件 |
| customer_destroy | 否 | 布尔 | 是否接收客户删除事件 |
| organization_create | 否 | 布尔 | 是否接收公司创建事件 |
| organization_update | 否 | 布尔 | 是否接收公司修改事件 |
| organization_destroy | 否 | 布尔 | 是否接收公司删除事件 |
| im_sub_session_close | 否 | 布尔 | 是否接收会话关闭事件 |
| shut_queue_create | 否 | 布尔 | 是否接收排队放弃事件 |
返回数据
| 属性名 | 类型 | 说明 |
|---|---|---|
| code | 整型 | 执行结果码，1000 代表成功 |
| permissions | 对象 | 修改后的设置集合，结构与参数相同 |
示例
curl https://demo.udesk.cn/open_api_v1/set_permissions?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X POST \
-H 'content-type: application/json' \
-d '
{
"permissions": {
"organization_create":true,
"organization_update": true,
"organization_destroy": true,
"customer_create": true,
"customer_update": true,
"customer_destroy": true,
"im_sub_session_close": true,
"shut_queue_create": true
}
}'
返回
{
"code": 1000,
"permissions": {
"organization_create": true,
"organization_update": true,
"organization_destroy": true,
"customer_create": true,
"customer_update": true,
"customer_destroy": true,
"im_sub_session_close": true,
"shut_queue_create": true
}
}
code错误码说明
| 错误码 | message信息 | exception:message信息 | 描述 |
|---|---|---|---|
| 2000 | 未知错误 | 对不起您传入的值不对 | 必填参数{content_type}未填写或值错误 |
| param is missing or the value is empty: permissions | 必填参数{permissions}未填写或为空值 |