Summary
Event callbacks, also known as Webhooks, refer to the mechanism where Udesk sends specific data in a fixed format to a designated callback address when a particular event occurs. Udesk's event callbacks support the following events:
| Event Name | Description |
|---|---|
| Customer_create | When a new customer is created |
| Customer_update | When a customer is updated |
| Customer_destroy | When a customer is deleted |
| Organization_create | When a new customer company is created |
| Organization_update | When a customer company is updated |
| Organization_destroy | When a customer company is deleted |
| ImSubSession_create | When an IM session is created |
| ImSubSession_close | When an IM session is closed |
| ShutQueue_create | When an IM session is abandoned |
| AgentNote_update | When a business record is modified after an IM session ends or a CC call ends |
| ImSurveyVote_create | When a conversation satisfaction is first saved |
| UserGroup_create | When a customer service group is created |
| UserGroup_update | When a customer service group name is modified or members are changed |
| UserGroup_destroy | When a customer service group is deleted |
| To use the Udesk event callback feature, you need to follow these steps: |
- Call the Udesk API address to register the callback interface address and subscribe to different types of events (both HTTP/HTTPS addresses are supported);
- Provide the interface address during registration, Udesk will notify different event messages based on the subscribed types.
Writing an Event Callback Handling Interface
This interface needs to be implemented by you and meet specific requirements.
Udesk will use the POST method to request the callback address you provided and will send the data as the request body (Request Body). Content-Type: application/json The structure of the request body is as follows:
| Attribute | Type | Description |
|---|---|---|
| action | String | Event type |
| message | Object | Event data |
The message content varies depending on the event. |
Customer_create Event
The message data structure refers to Customer Data.
Example:
{
"action": "Customer_create",
"message": {
"id": 1,
"nick_name": "Test User",
"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": "Manual entry"
}
}
Customer_update Event
The message data structure is as follows:
{
"id": "customer_id",
"changes": {
"attribute_name": ["original_value", "new_value"]
}
}
The attribute_name refers to Customer Data.
Example:
{
"action": "Customer_update",
"message": {
"id": 1,
"changes": {
"nick_name": ["test customer 1", "test customer 2"],
"owner_id": [1, 2]
}
}
}
Customer_destroy Event
The message data structure is as follows:
{
"id": "deleted_customer_id"
}
Example:
{
"action": "Customer_destroy",
"message": {
"id": 1
}
}
Organization_create Event
The message data structure refers to Customer Company Data.
Example:
{
"action": "Organization_create",
"message": {
"id": 1,
"name": "test company 1",
"domains": "https://www.test1.com",
"custom_fields": {
"TextField_1": "demo",
"SelectField_1": ["0"]
},
"description": "The company is used solely for example purposes."
}
}
Organization_update Event
The message data structure is as follows:
{
"id": "customer_company_id",
"changes": {
"attribute_name": ["original_value", "new_value"]
}
}
The attribute_name refers to Customer Company Data.
Example:
{
"action": "Organization_update",
"message": {
"id": 1,
"changes": {
"name": ["test company 1", "test company 2"]
}
}
}
Organization_destroy Event
The message data structure is as follows:
{
"id": "deleted_customer_company_id"
}
Example:
{
"action": "Organization_destroy",
"message": {
"id": 1
}
}
ImSubSession_create Event
The message data structure is as follows:
{
"id": "newly_created_session_id",
"im_sub_session_log": "dialogue_record_details"
}
Example:
{
"action": "ImSubSession_create",
"message": {
"id": 14980761,
"im_sub_session_log": [
{
"session_id": 8761,
"sub_session_id": 14980761,
"agent_id": 862,
"customer_id": 117092,
"platform": "weixin",
"source": "weixin-xx",
"weifeng": "weifeng_params",
"created_at": "2017-10-27 21:23:45"
}
]
}
}
ImSubSession_close Event
The message data structure is as follows:
{
"id": "closed_session_id",
"im_sub_session_log": "dialogue_record_details",
"im_log_infos": "chat_records"
}
Example:
{
"action": "ImSubSession_close",
"message": {
"id": 14980761,
"im_sub_session_log": [
{
"session_id": 8761,
"sub_session_id": 14980761,
"note_id": 6541,
"note_content": "business_record_subject",
"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":"example",
"SelectField_2":"0,0",
"SelectField_3":"2",
"SelectField_4":"0,1,2,3,4"
},
"note_template_id": "business_record_template_id",
"note_template_name": "business_record_template_name",
"customer_id": 117092,
"customer_name": "xx",
"customer_custom_fields":{
"TextField_1":"customer_custom_field",
"TextField_2":"2018-07-01",
"TextField_3":"00:02:02",
"TextField_4":"21",
"TextField_5":"25",
"SelectField_1":"0",
"TextField_7":"test_content",
"SelectField_2":"0,0",
"SelectField_3":"2",
"SelectField_4":"0,1,2,3,4"
},
"agent_id": 862,
"agent_nick_name": "xx_agent ",
"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": "Not In Queue",
"sustain_seconds": 14,
"survey_vote_id": null,
"platform": "weixin",
"belong_queue": "queue_company_6_group_271",
"agent_msg_num": 1,
"customer_msg_num": 1,
"source": "weixin-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": "sensitive_word_1_time, response_timeout, session_timeout",
"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": ["customer_tag_1", "customer_tag_2", "customer_tag_3"],
"weixin_info": {
"name": "weixin_channel_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>Agent xx_agent is at your service</p><p>Lalala - English</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\":\"There is a new inquiry coming in.。\",\"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\":\"Hello weixin\",\"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\":\"normal\",\"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_agent close chat\",\"duration\":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": "arrive"
}
]
}
}
Notes:
1. Conversation End Method - close_method:
"agent_close" | Closed by Agent
"redirect_close" | Closed after Redirect
"sys_close" | Closed by System
"customer_close" | Closed by Customer
2. Message Send Status - send_status:
"sending" | Sending
"arrive" | Delivered
"fail" | Sending Failed
"off_sending" | Offline Sending
"off_arrive" | Offline Delivered
"rollback" | Message Recalled
3. Robot Session ID - robot_session_id:
The robot session ID on the customer service system side.
4. Satisfaction - Resolution State - resolved_state:
"0" | Resolved
"1" | Unresolved
ShutQueue_create Event
The data structure of the "message" is as follows:
{
"id": Record ID,
"customer_id": Customer ID,
"nick_name": Customer Name,
"queue_name": Name of the Queue,
"queue_type": Type of the Queue,
"queue_id": Queue Staff Group ID or Staff ID,
"queue_start_time": Queue Start Time,
"queue_end_time": Queue End Time,
"queue_seconds": Duration of the Queue,
"chanel": Channel,
"im_web_plugin_id": Source Plugin ID,
"menu_names": Navigation Menu Name
}
Example:
{
"action": "ShutQueue_create",
"message": {
"id": "1",
"customer_id": "46",
"nick_name": "Beijing cloud-ark.cn Unicom (1535800080)",
"queue_name": "Queue Customer Service 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 seconds",
"chanel": "web",
"im_web_plugin_id": 1,
"menu_names": "Navigation Menu Name"
}
}
Note:
When the queue is for customer service, queue_name is the name of the customer service, queue_type is "agent", and queue_id is the customer service ID.
When the queue is for a customer service group, queue_name is the name of the customer service group, queue_type is "group", and queue_id is the customer service group ID.
When the queue is for a company, queue_name is "company", queue_type is "company", and queue_id is "company".
AgentNote_update Event
The data structure of the "message" is as follows: For IM conversation business record updates, the data structure is as follows:
{
"updated_at": Modification time, accurate to the second,
"sub_session_id": Conversation ID,
"note_id": Business record ID,
"note_content": Business record subject,
"field_id": Field ID,
"field_title": Field name,
"filed_value": Modified field value
}
For CC call business record updates, the data structure is as follows:
{
"updated_at": Modification time, accurate to the second,
"conversation_id": Call record ID,
"note_id": Business record ID,
"note_content": Business record subject,
"field_id": Field ID,
"field_title": Field name,
"filed_value": Modified field value
}
Example (IM):
{
"action": "AgentNote_update",
"message": {
"updated_at": "2019-12-06 10:02:40",
"sub_session_id": 4947,
"note_id": 292,
"note_content": "Business record subject",
"field_id": "SelectField_98",
"field_title": "Complaint Type",
"filed_value": "0"
}
}
Example (CC):
{
"action": "AgentNote_update",
"message": {
"updated_at": "2019-12-06 10:02:40",
"conversation_id": 4947,
"note_id": 292,
"note_content": "Business record subject",
"field_id": "SelectField_98",
"field_title": "Complaint Type",
"filed_value": "0"
}
}
Notes:
1. The event callback is triggered only for business record modifications made after the conversation is closed.
2. Business record modifications made through the API do not trigger event callbacks.
ImSurveyVote_create Event
The data structure of the "message" is as follows:
{
"created_at": Save time, accurate to the second,
"sub_session_id": Conversation ID,
"option_id": Satisfaction option ID,
"option_name": Satisfaction option name,
"tags": Satisfaction tag names,
"remark": Value of the remark
}
Example:
{
"action": "ImSurveyVote_create",
"message": {
"created_at": "2019-12-06 10:13:04",
"sub_session_id": 4947,
"option_id": 1234,
"option_name": "Very Satisfied",
"tags": "Tag 1, Tag 2",
"remark": "Remark"
}
}
UserGroup_create Event
The data structure of the "message" is as follows:
{
"id": User Group ID,
"name": User Group Name
}
Example:
{
"action": "UserGroup_create",
"message": {
"id": 1,
"name": "Default Group"
}
}
UserGroup_update Event
Note: The return result only includes the modified fields; other fields are not returned. The data structure of the "message" is as follows:
{
"id": User Group ID,
"changes": {
"name": [Original user group name, New user group name after the change],
"add_agent_id": Added agent ID,
"del_agent_id": Deleted agent ID
}
}
Example:
{
"action": "UserGroup_update",
"message": {
"id": 1,
"changes": {
"name": ["Customer Service Group 1", "Customer Service Group 2"],
"add_agent_id": 1,
"del_agent_id": 2
}
}
}
UserGroup_destroy Event
The data structure of the "message" is as follows:
{
"id": ID of the deleted user group
}
Example:
{
"action": "UserGroup_destroy",
"message": {
"id": 1
}
}
New Event Callback Interface
This interface is used to set the event callback URL. Authentication: Refer to the Authentication Method
Request Method
POST /webhook_create
Request Parameters (Request Body)
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| push_url | Yes | String | Event callback URL |
| permissions | Yes | JSON Object | Event set |
permissions Data Structure
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| customer_create | No | Boolean | Whether to receive customer creation events |
| customer_update | No | Boolean | Whether to receive customer update events |
| customer_destroy | No | Boolean | Whether to receive customer deletion events |
| organization_create | No | Boolean | Whether to receive company creation events |
| organization_update | No | Boolean | Whether to receive company update events |
| organization_destroy | No | Boolean | Whether to receive company deletion events |
| im_sub_session_close | No | Boolean | Whether to receive session closure events |
| shut_queue_create | No | Boolean | Whether to receive queue abandonment events |
| im_survey_vote_create | No | Boolean | Whether to receive satisfaction evaluation events |
| agent_note_update | No | Boolean | Whether to receive business record modification events |
| user_group_create | No | Boolean | Whether to receive customer service group creation events |
| user_group_update | No | Boolean | Whether to receive customer service group update events |
| user_group_destroy | No | Boolean | Whether to receive customer service group deletion events |
Example
curl https://demo.udesk.cn/open_api_v1/webhook_create?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",
"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
}
}'
Response
{
"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
}
}
}
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| webhook | Object | The updated settings collection, with the same structure as the parameters |
Edit Event Callback
This interface is used to update the event callback URL. Authentication: Refer to the Authentication Method
Request Method
POST /webhook_update
Request Parameters (Request Body)
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| push_url | Yes | String | Event callback URL |
| permissions | Yes | JSON Object | Event set, refer to the creation section for details |
Example
curl https://demo.udesk.cn/open_api_v1/webhook_update?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",
"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
}
}'
Response
{
"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
}
}
}
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| webhook | Object | The updated settings collection, with the same structure as the parameters |
Delete Event Callback
This interface is used to delete the event callback URL. Authentication: Refer to the Authentication Method
Request Method
POST /webhook_destroy
Request Parameters (Request Body)
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| push_url | Yes | String | Event callback URL |
Example
curl https://demo.udesk.cn/open_api_v1/webhook_destroy?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"
}'
Response
{
"code": 1000
}
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
Query All Event Callback URLs Interface
This interface is used to retrieve all set event callback URLs. Authentication: Refer to the Authentication Method
Request Method
POST /webhook_list
Request Parameters (Request Body)
None
Response Data
| Attribute Name | Type | Description |
|---|---|---|
| code | Integer | Execution result code, 1000 represents success |
| webhooks | JSON Object | Array of webhook objects |
Example
curl -X POST \
'https://demo.udesk.cn/open_api_v1/webhook_list?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2' \
--header 'Content-Type: application/json' \
--data '{}'
Response
{
"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
}
}
]
}
Error Code Description
| Error Code | message Information | exception:message Information | Description |
|---|---|---|---|
| 2000 | Unknown Error | Sorry, the value you entered is incorrect | Required parameter {content_type} not filled in or value is incorrect |
| param is missing or the value is empty: permissions | Required parameter {permissions} not filled in or is empty |