概要

事件回调,又称 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 事件回调功能,您要执行以下步骤:

  1. 编写代码,实现事件回调处理接口,并提供事件回调地址;
  2. 调用设置事件回调地址接口,将您实现的事件回调处理接口地址设置事件回调地址;
  3. 调用设置事件回调类型接口,根据您的需要设置需要接收哪些事件回调;
  4. 调用设置事件回调的 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&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,
  "push_url": "https://www.demo.com/push_url"
}

设置事件回调的 content_type 接口

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

请求方法

POST /set_push_content_type

请求参数(Request Body)

参数名 必填 类型 说明
push_content_type 字符串 事件回调请求的 content_type

返回数据

属性名 类型 说明
code 整型 执行结果码,1000 代表成功
webhook_push_type 字符串 回调返回值的结构

示例

curl https://demo.udesk.cn/open_api_v1/set_push_content_type?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_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&timestamp=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}未填写或为空值