事件回调

概要

事件回调,又称 Webhook,是指当特定事件发生时,Udesk 将特定的数据以固定的格式发送给您指定的回调地址。

Udesk 的事件回调支持以下事件:

事件名 说明
Customer_create 新建客户时
Customer_update 修改客户时
Customer_destroy 删除客户时
Organization_create 新建客户公司时
Organization_update 修改客户公司时
Organization_destroy 删除客户公司时
ImSubSession_close IM会话关闭时
ShutQueue_create IM放弃排队时

如果需要使用 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": "http://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_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": null,
          "customer_id": 117092,
          "customer_name": "xx",
          "customer_custom_fields": {},
          "agent_id": 862,
          "agent_nick_name": "xx_客服",
          "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",
          "im_web_plugin_id": 1,
          "sender": "customer",
          "active_guest": "agent",
          "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://qn-im.udesk.cn/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
          },
          {
          "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
          },
          {
          "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
          },
          {
          "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
          },
          {
          "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
         }
          {
          "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
         }
        ]
    }
}

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": 渠道
}

示例

{
    "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"
    }
}
备注:
当排队队列为客服时,queue_name是客服名称,queue_type是“agent”,queue_id是客服id
当排队队列为客服组时,queue_name是客服组名称,queue_type是“group”,queue_id是客服组id
当排队队列为公司时,queue_name是“公司”,queue_type是“company”,queue_id是“公司“

设置事件回调地址接口

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

请求方法

POST /set_url

请求参数(Request Body)

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

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
message 字符串 返回结果说明
push_url 字符串 修改后的事件回调地址

示例

curl http://demo.udesk.cn/open_api_v1/set_url?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8
-X POST \
-H 'content-type: application/json' \
-d '
{
    "push_url": "http://www.demo.com/push_url"
}'

返回

{
    "code": 1000,
    "message": "OK",
    "push_url": "http://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 http://demo.udesk.cn/open_api_v1/set_push_content_type?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8
-X POST \
-H 'content-type: application/json' \
-d '
{
    "push_content_type": "JSON"
}'

返回

{
    "code": 1000,
    "webhook_push_type": "JSON"
}

设置事件回调类型接口

该接口用于设置需要接收哪些事件回调 鉴权:参看鉴权方法

请求方法

POST /set_url/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代表成功
message 字符串 返回结果说明
permissions 对象 修改后的设置集合,结构与参数相同

示例

curl http://demo.udesk.cn/open_api_v1/set_permissions?email=admin@udesk.cn&timestamp=1494474404&sign=2f4c2c3d0b4c24cfa4feca76e237da0c368a00d8 \
-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,
    "message": "OK",
    "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
    }
}