Udesk-Customer service solution leader

Overview

Event callbacks, also known as Webhooks, refer to the transmission of specific data in a fixed format to the specified callback address when a specific 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 a new IM sub-session is created
ImSubSession_close	When an IM sub-session is closed
ShutQueue_create	When an IM queue is abandoned
AgentNote_update	When business notes are updated after IM session ends/CC call ends
ImSurveyVote_create	When conversation satisfaction is saved

If you need to use Udesk's event callback feature, you need to follow these steps:

Write code to implement the event callback processing interface and provide an event callback address;
Call the set event callback address interface to set the event callback address for the implemented event callback processing interface;
Call the set event callback type interface to set which event callbacks you need to receive based on your needs;
Call the set event callback's content_type interface to set the content_type value based on your needs.

Writing an Event Callback Handling Interface

You need to implement this interface and meet specific requirements.

Udesk will make a POST request to the callback address you provide and will send the data in the request body (Request Body). The structure of the request body data is as follows:

Attribute	Type	Description
action	String	Event type
message	Object	Event data

The message content varies for different events.

Customer_create Event

The data structure for the message field 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 data structure for the message field 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 data structure for the message field is as follows:

{
  "id": customer_id_deleted
}

Example:

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

Organization_create Event

The data structure for the message field refers to Organization 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": "company description"
  }
}

Organization_update Event

The data structure for the message field is as follows:

{
  "id": organization_id,
  "changes": {
    "attribute_name": [original_value, new_value]
  }
}

The attribute_name refers to Organization Data. Example:

{
  "action": "Organization_update",
  "message": {
    "id": 1,
    "changes": {
      "name": ["test company 1", "test company 2"]
    }
  }
}

Organization_destroy Event

The data structure for the message field is as follows:

{
  "id": organization_id_deleted
}

Example:

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

ImSubSession_create Event

The data structure for the message field is as follows:

{
  "id": newly_created_session_id,
  "im_sub_session_log": details_of_conversation_log
}

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 data structure for the message field is as follows:

{
  "id": session_id_closed,
  "im_sub_session_log": details_of_conversation_log,
  "im_log_infos": chat_log
}

Example:

{
    "action": "ImSubSession_close",
    "message": {
        "id": 14980761,
        "im_sub_session_log": [
          {
          "session_id": 8761,
          "sub_session_id": 14980761,
          "note_id": 6541,
          "note_content": "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": {},
          "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 once, 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 tag1", "customer tag2", "customer tag3"],
          "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>agent xx_agent is at your service.</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 new consultation 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"
         }
        ]
    }
}

Note：
1、Dialogue end method-close_method:
"agent_close"    | agent close
"redirect_close" | transfer close
"sys_close"      | system close
"customer_close" | customer close
2、Message sending status-send_status:
"sending"        | sending
"arrive"         | arrive
"fail"           | send fail
"off_sending"    | Offline sending
"off_arrive"     | Offline delivery
"rollback"       | Recalled
3、robot chat ID-robot_session_id:
agent System-side robot session ID
4、Satisfaction - Has the issue been resolved?-resolved_state:
"0"              | Resolved
"1"              | Unresolved

ShutQueue_create Event

The data structure for the message field is as follows:

{
    "id": record_id,
    "customer_id": customer_id,
    "nick_name": customer_name,
    "queue_name": queue_name,
    "queue_type": queue_type,
    "queue_id": queue_id,
    "queue_start_time": queue_start_time,
    "queue_end_time": queue_end_time,
    "queue_seconds": queue_duration,
    "channel": 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": "Queueing agent 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": "30s",
    "channel": "web",
    "im_web_plugin_id": 1,
    "menu_names": "Navigation menu name"
  }
}

Notes:

If the queue is for an agent, queue_name will be the agent's name, queue_type will be "agent", and queue_id will be the agent's ID.
If the queue is for an agent group, queue_name will be the group's name, queue_type will be "group", and queue_id will be the group's ID.
If the queue is for a company, queue_name will be "company ", queue_type will be "company", and queue_id will be "company ".

AgentNote_update Event

The data structure for the message field varies depending on whether the update is for an IM conversation or a CC call. For IM conversations:

{
  "updated_at": update_time_to_seconds,
  "sub_session_id": conversation_id,
  "note_id": business_record_id,
  "note_content": business_record_title,
  "field_id": field_id,
  "field_title": field_name,
  "filed_value": updated_field_value
}

For CC calls:

{
  "updated_at": update_time_to_seconds,
  "conversation_id": call_record_id,
  "note_id": business_record_id,
  "note_content": business_record_title,
  "field_id": field_id,
  "field_title": field_name,
  "filed_value": updated_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": "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": "subject",
    "field_id": "SelectField_98",
    "field_title": "Complaint type",
    "filed_value": "0"
  }
}

Notes:

The business record update is only triggered after the conversation is closed.
Business record updates through the API do not trigger event callbacks.

ImSurveyVote_create Event

The data structure for the message field is as follows:

{
  "created_at": save_time_to_seconds,
  "sub_session_id": conversation_id,
  "option_id": satisfaction_option_id,
  "option_name": satisfaction_option_name,
  "tags": satisfaction_labels,
  "remark": remark_value
}

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": "tag1,tag2",
    "remark": "remark example"
  }
}

Setting the Event Callback URL Interface

This interface is used to set the event callback URL. Authentication: See Authentication Methods

Request Method

POST /set_url

Request Parameters (Request Body)

Parameter Name	Required	Type	Description
push_url	Yes	String	Event callback URL

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
push_url	String	Modified event callback URL

Example

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"
}'

Return

{
  "code": 1000,
  "push_url": "https://www.demo.com/push_url"
}

Setting the Event Callback Content-Type Interface

This interface is used to set the content type for event callbacks. Authentication: See Authentication Methods

Request Method

POST /set_push_content_type

Request Parameters (Request Body)

Parameter Name	Required	Type	Description
push_content_type	Yes	String	The content type for event callbacks

Note: push_content_type can be passed as JSON, and the corresponding return value is a JSON string. The default value is "application/x-www-form-urlencoded".

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
webhook_push_type	String	The structure of the callback response

Example

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"
}'

Return

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

Setting the Event Callback Type Interface

This interface is used to set which event callbacks need to be received. Authentication: See Authentication Methods

Request Method

POST /set_permissions

Request Parameters (Request Body)

Parameter Name	Required	Type	Description
permissions	Yes	Object	Setting collection

Data Structure of `permissions`

Parameter Name	Required	Type	Description
customer_create	No	Boolean	Whether to receive customer create events
customer_update	No	Boolean	Whether to receive customer update events
customer_destroy	No	Boolean	Whether to receive customer destroy events
organization_create	No	Boolean	Whether to receive organization create events
organization_update	No	Boolean	Whether to receive organization update events
organization_destroy	No	Boolean	Whether to receive organization destroy events
im_sub_session_close	No	Boolean	Whether to receive session close events
shut_queue_create	No	Boolean	Whether to receive queue abandon events

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
permissions	Object	Modified setting collection, same structure as parameters

Example

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
    }
}'

Return

{
  "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 Error Code Description

Error Code	Message Information	exception:Message Information	Description
2000	Unknown error	sorry you entered an incorrect value	Required parameter {content_type} is missing or has an incorrect value
		param is missing or the value is empty: permissions	Required parameter {permissions} is missing or empty

Overview

Writing an Event Callback Handling Interface

Customer_create Event

Customer_update Event

Customer_destroy Event

Organization_create Event

Organization_update Event

Organization_destroy Event

ImSubSession_create Event

ImSubSession_close Event

ShutQueue_create Event

AgentNote_update Event

ImSurveyVote_create Event

Setting the Event Callback URL Interface

Request Method

Request Parameters (Request Body)

Return Data

Example

Setting the Event Callback Content-Type Interface

Request Method

Request Parameters (Request Body)

Return Data

Example

Setting the Event Callback Type Interface

Request Method

Request Parameters (Request Body)

Data Structure of `permissions`

Return Data

Example

Code Error Code Description

Products

Solutions

Resources

Overview

Writing an Event Callback Handling Interface

Customer_create Event

Customer_update Event

Customer_destroy Event

Organization_create Event

Organization_update Event

Organization_destroy Event

ImSubSession_create Event

ImSubSession_close Event

ShutQueue_create Event

AgentNote_update Event

ImSurveyVote_create Event

Setting the Event Callback URL Interface

Request Method

Request Parameters (Request Body)

Return Data

Example

Setting the Event Callback Content-Type Interface

Request Method

Request Parameters (Request Body)

Return Data

Example

Setting the Event Callback Type Interface

Request Method

Request Parameters (Request Body)

Data Structure of permissions

Return Data

Example

Code Error Code Description

Products

Solutions

Resources

Data Structure of `permissions`