事件回调 - Udesk | 开发者中心

概要

事件回调，又称 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	对话满意度第一次保存时
UserGroup_create	客服组创建时
UserGroup_update	客服组名称修改、客服组人员修改时
UserGroup_destroy	客服组删除时

如果需要使用 Udesk 事件回调功能，您要执行以下步骤：

调用Udesk接口地址，实现回调接口的地址注册，订阅不同的类型事件（http/https地址均支持）；
提供注册时接口地址，Udesk会根据订阅的类型通知不同事件消息格式；

编写事件回调处理接口

该接口需要由您实现，并且满足特定的要求。

Udesk 会使用 POST 方法请求您提供的回调地址，并将数据作为请求体（Request Body）传送。

Content-Type: application/json

请求体的数据结构如下：

属性	类型	说明
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":{
             "TextField_1":"客户自定义字段",
             "TextField_2":"2018-07-01",
             "TextField_3":"00:02:02",
             "TextField_4":"21",
             "TextField_5":"25",
             "SelectField_1":"0",
             "TextField_7":"测试内容",
             "SelectField_2":"0,0",
             "SelectField_3":"2",
             "SelectField_4":"0,1,2,3,4"
          },
          "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": "微信渠道名字"
          }
        ],
        "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": "备注"
  }
}

UserGroup_create 事件

“message”的数据结构如下：

{
  "id": 客服组ID,
  "name": 客服组名称
}

示例

{
  "action": "UserGroup_create",
  "message": {
    "id": 1,
    "name": "默认组"
  }
}

UserGroup_update 事件

注: 返回结果只返回被修改字段,其他字段不返回

“message”的数据结构如下：

{
  "id": 客服组ID,
  "changes": {
    "name": [客服组名称原值, 客服组名称变更后的值],
    "add_agent_id": 增加的客服ID,
    "del_agent_id": 删除的客服ID
  }
}

示例

{
  "action": "UserGroup_update",
  "message": {
    "id": 1,
    "name": ["客服组1", "客服组2"],
    "add_agent_id": 1,
    "del_agent_id": 2
  }
}

UserGroup_destroy 事件

“message”的数据结构如下：

{
  "id": 被删除的客服组ID
}

示例

{
  "action": "UserGroup_destroy",
  "message": {
    "id": 1
  }
}

新增事件回调接口

该接口用于设置事件回调地址鉴权：参看鉴权方法

请求方法

POST /webhook_create

请求参数（Request Body）

参数名	必填	类型	说明
push_url	是	字符串	事件回调地址
permissions	是	JSON对象	事件集合

permissions 的数据结构

参数名	必填	类型	说明
customer_create	否	布尔	是否接收客户创建事件
customer_update	否	布尔	是否接收客户修改事件
customer_destroy	否	布尔	是否接收客户删除事件
organization_create	否	布尔	是否接收公司创建事件
organization_update	否	布尔	是否接收公司修改事件
organization_destroy	否	布尔	是否接收公司删除事件
im_sub_session_close	否	布尔	是否接收会话关闭事件
shut_queue_create	否	布尔	是否接收排队放弃事件
im_survey_vote_create	否	布尔	是否接收满意度评价事件
agent_note_update	否	布尔	是否接收业务记录修改事件
user_group_create	否	布尔	是否接收客服组创建事件
user_group_update	否	布尔	是否接收客服组更新事件
user_group_destroy	否	布尔	是否接收客服组删除事件

示例

curl https://demo.udesk.cn/open_api_v1/webhook_create?email=admin@udesk.cn&timestamp=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",
    "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,
  "webhook": 
    {
      "push_url": "https://www.demo.com/push_url",
      "permissions": {
          "organization_create":true,
          "organization_update":true,
          "organization_destroy":true,
          "customer_create":true,
          "customer_destroy":true,
          "customer_update":true,
          "im_sub_session_close":true,
          "shut_queue_create":true
      }
    }
}

返回数据

属性名	类型	说明
code	整型	执行结果码，1000 代表成功
webhook	对象	修改后的设置集合，结构与参数相同

编缉事件回调

该接口用于设置事件回调地址鉴权：参看鉴权方法

请求方法

POST /webhook_update

请求参数（Request Body）

参数名	必填	类型	说明
push_url	是	字符串	事件回调地址
permissions	是	JSON对象	事件集合参考创建

示例

curl https://demo.udesk.cn/open_api_v1/webhook_update?email=admin@udesk.cn&timestamp=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",
    "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,
  "webhook": 
    {
      "push_url": "https://www.demo.com/push_url",
      "permissions": {
          "organization_create":true,
          "organization_update":true,
          "organization_destroy":true,
          "customer_create":true,
          "customer_destroy":true,
          "customer_update":true,
          "im_sub_session_close":true,
          "shut_queue_create":true
      }
    }
}

返回数据

属性名	类型	说明
code	整型	执行结果码，1000 代表成功
webhook	对象	修改后的设置集合，结构与参数相同

删除事件回调

该接口用于设置事件回调地址鉴权：参看鉴权方法

请求方法

POST /webhook_destroy

请求参数（Request Body）

参数名	必填	类型	说明
push_url	是	字符串	事件回调地址

示例

curl https://demo.udesk.cn/open_api_v1/webhook_destroy?email=admin@udesk.cn&timestamp=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
}

返回数据

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

查询所有事件回调地址接口

该接口用于设置事件回调地址鉴权：参看鉴权方法

请求方法

POST /webhook_list

请求参数（Request Body）

无

返回数据

属性名	类型	说明
code	整型	执行结果码，1000 代表成功
webhooks	JSON对象	数组列表

示例

curl -X POST \
    'https://demo.udesk.cn/open_api_v1/webhook_list?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2' \
    --header 'Content-Type: application/json' \
    --data '{}'

{
  "code": 1000,
  "webhooks": [
    {
      "push_url": "http://localhost:3002",
      "permissions": {
          "organization_create":true,
          "organization_update":true,
          "organization_destroy":true,
          "customer_create":true,
          "customer_destroy":true,
          "customer_update":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}未填写或为空值

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

概要

编写事件回调处理接口

Customer_create 事件

Customer_update 事件

Customer_destroy 事件

Organization_create 事件

Organization_update 事件

Organization_destroy 事件

ImSubSession_create 事件

ImSubSession_close 事件

ShutQueue_create 事件

AgentNote_update 事件

ImSurveyVote_create 事件

UserGroup_create 事件

UserGroup_update 事件

UserGroup_destroy 事件

新增事件回调接口

请求方法

请求参数（Request Body）

permissions 的数据结构

示例

返回数据

编缉事件回调

请求方法

请求参数（Request Body）

示例

返回数据

删除事件回调

请求方法

请求参数（Request Body）

示例

返回数据

查询所有事件回调地址接口

请求方法

请求参数（Request Body）

返回数据

示例

code错误码说明

文档反馈