Udesk-Customer service solution leader

Meaning of Values for Some Fields in Work Orders

Range of Values for status_id

Value	English Name
1	open
2	resolved
3	closed
4	solving

Range of Values for priority_id

Value	Name
1	urgency
2	high
3	medium
4	low

Range of Values for platform_name

Value	Meaning
email	eamil
weibo	weibo
wechat	weixin
im	Real-time chat
call	Telephone
feedback	Feedback tag
hc	help center
manual_input	Manual entry
api	API

Description of Pagination in Return Values

If the return value includes pagination-related content, we use the object meta to represent it, with the following structure: Structure of meta data

Attribute	Type	Description
current_page	Integer	Current page
total_pages	Integer	Total number of pages
total_count	Integer	Total number of data records

Create Work Order

This interface is used to create a work order.

Request Method

POST /tickets

Request Parameters (Request Body)

Parameter Name	Type	Required	Description
ticket	Object	Yes	Work order information, see below

Structure of ticket

Parameter Name	Type	Required	Description	Restrictions
subject	String	Yes	Title	Maximum length of 255 characters
content	String	Yes	Content
type	String	No	Type used to find the customer
type_content	String	No	Value corresponding to the type	Maximum length of 255 characters
priority	String	No	Chinese name of priority, default is standard
assignee_email	String	No	Email of the handling customer service	Maximum length of 255 characters
agent_group_name	String	No	Name of the handling customer service group	Maximum length of 255 characters
template_id	Integer	No	Work order template id, use default template if no value is passed or an incorrect value is passed
follower_ids	Array	No	Work order followers, e.g., [1,2,3], the array contains customer service ids
tags	String	No	Work order tags, e.g., "Tag1, Tag2", the string contains tag names separated by commas
status_id	Integer	No	Status id
ticket_field	Object	No	Custom fields, see below
creator_email	String	No	Email of the person who created the work order	Maximum length of 255 characters

ticket_field

The attributes of ticket_field are the identifiers of custom fields;
For selection types, use the index value of the options, and concatenate multiple selections into a string with commas.
For text type custom fields, their values are strings with specific formats;
Refer to the type description in "Add New Field - Select Field Type" in the customer service system.

Notes:

When creating a work order, if type or type_content is not empty, we will find the customer based on type and type_content. If the customer cannot be found, an error message will be returned; you can use the interface to create a customer;
When creating a work order, if both type and type_content are empty, we will not find the customer based on type and type_content. In this case, the customer information for the new work order will be empty.
There are four possible values for type: email (customer email), cellphone (customer phone), customer_token (customer's external unique identifier), customer_id (customer id). In one call, the value of type can only be one of these.
The value of type_content must correspond to the type. When type is email, type_content should be the email value.

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
message	String	Execution result explanation
ticket_id	Integer	Id of the newly created work order

Example

Request

curl https://demo.udesk.cn/open_api_v1/tickets?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 '
{
    "ticket": {
        "subject":"Demo Ticket1",
        "content":"ticket demo",
        "follower_ids":["1","23","12"],
        "template_id":3,
        "tags":"tag2,tag1",
        "type":"customer_id",
        "type_content":"2",
        "priority":"normal",
        "status_id":1,
        "agent_group_name":"default group",
        "assignee_email":"agent@sample.com",
        "ticket_field":{
            "TextField_1": "Plain text content",
            "TextField_2": "Multiline text content 1\r\nMultiline text content 2",
            "TextField_3": "2016-08-11",
            "TextField_4": "14:44:36",
            "TextField_5": "2017-05-03 14:44",
            "TextField_6": "https://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "TextField_9": "My geographical location",
            "SelectField_1": "0",
            "SelectField_2": "0",
            "SelectField_3": "0,3"
        }
    }
}'

return

{
    "code":1000,
    "message":"ticket create success",
    "ticket_id":2
}

Retrieve Work Order Details

This interface is used to obtain detailed information about a specified work order.

Request Method

GET /tickets/detail

Request Parameters (Request String)

Parameter Name	Type	Required	Description
id	Integer	No	Work order id
num	String	No	Work order number, e.g., num='#848'

Note: Only one of id and num can be passed, but one of them must be passed; the value of num '#848' needs to be URL encoded as '%23848'.

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
message	String	Execution result explanation
ticket	Object	Work order information, structure below

Data Structure of Work Order

Attribute Name	Type	Editable	Description
id	Integer	No	Unique identifier, automatically generated by the system
field_num	String	No	Unique identifier, automatically generated by the system
subject	String	Yes	Title
content	String	Yes	Content
content_type	String	Yes	Content type
user_id	Integer	Yes	Customer id
user_name	String	No	Customer name
user_email	String	No	Customer email
user_cellphone	String	No	Customer phone
organization_id	Integer	No	Customer's company id
assignee_id	Integer	Yes	Handling customer service id
assignee_name	String	No	Handling customer service name
assignee_avatar	String	No	Handling customer service avatar
user_group_id	Integer	Yes	Handling customer service group id
user_group_name	String	No	Handling customer service group name
template_id	Integer	No	Template id
priority	String	Yes	Priority in Chinese name
status	String	Yes	Status in Chinese name
status_en	String	Yes	Status in English name
platform	String	No	Channel in Chinese name
satisfaction	String	No	Satisfaction survey result
custom_fields	Object	Yes	Custom fields, see example
tags	String	Yes	Tags
followers	Array	No	Followers, including id (follower id), nick_name (follower name)
creator_id	Integer	No	Creator
created_at	DateTime	No	Creation time, automatically generated by the system
updated_at	DateTime	No	Update time, automatically generated by the system
solving_at	DateTime	No	Time of starting to solve
resolved_at	DateTime	No	Resolution time
closed_at	DateTime	No	Closure time
solved_deadline	DateTime	No	Deadline
replied_at	DateTime	No	Last reply time
agent_replied_at	DateTime	No	Last reply time by customer service
customer_replied_at	DateTime	No	Last reply time by customer
replied_by	String	No	Last person to reply
attachments	Array	No	Attachments associated with the work order, including file_name (file name), url (file URL)
im_sub_session_id	Integer	No	Session ID of the work order
associated_tickets	Array	No	Associated work order data, including work order id, work order number, associated type name, only returned in detail

Example

Request

curl https://demo.udesk.cn/open_api_v1/tickets/detail?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&id=1

Return

{
    "code": 1000,
    "message": "success",
    "ticket": {
        "id": 1,
        "field_num": "#1",
        "subject": "hello！",
        "content": "<p>hello world</p>",
        "content_type": "html",
        "user_id": 47,
        "user_name": "13000020520",
        "user_email": "1234567890@qq.com",
        "user_cellphone": "13000020520",
        "organization_id": null,
        "assignee_id": 12,
        "assignee_name": "xxx",
        "assignee_avatar": "https://xxxxxxxxxxxxxxxxx/Fk_5aUhOY0U90dHQU6V34N9WuqX9",
        "user_group_id": 1,
        "user_group_name": "default group",
        "template_id": 1,
        "priority": "noraml",
        "status": "open",
        "status_en": "open",
        "platform": "Manual entry",
        "im_sub_session_id": 1257,
        "satisfaction": null,
        "custom_fields": {
            "TextField_3": "test",
            "SelectField_3": "0",
            "SelectField_4": "0",
            "TextField_38": "demo",
            "TextField_40": "text"
        },
        "tags": "tag１,tag２",
        "followers": [
            {
                "id": 2,
                "nick_name": "Tom"
            },
            {
                "id": 3,
                "nick_name": "Jerry"
            },
            {
                "id": 12,
                "nick_name": "Lucy"
            }
        ],
        "attachments": [
           {
                "name": "attachment1",
                "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
            },
        ],
        "creator_id": 1,
        "created_at": "2017-08-08T20:47:49.000+08:00",
        "updated_at": "2017-08-18T12:06:02.000+08:00",
        "solving_at": null,
        "resolved_at": null,
        "closed_at": null,
        "solved_deadline": null,
        "replied_at": "2017-08-16T20:41:03.000+08:00",
        "agent_replied_at": "2017-08-16T20:41:03.000+08:00",
        "customer_replied_at": "2017-08-08T20:47:42.000+08:00",
        "replied_by": "xxx",
        "associated_tickets": [
            {
                "id": 2,
                "field_num": "#002",
                "associated_type": "repeat ticket"
            },
            {
                "id": 3,
                "field_num": "#003",
                "associated_type": "sub ticket"
            }
        ]
    }
}

Update Ticket

This interface is used to modify ticket information

Request Method

PUT /tickets/:id

URL Request Parameters

Parameter Name	Required	Description
id	Yes	Ticket ID

Request Body Parameters

Parameter Name	Type	Required	Description
ticket	Object	Yes	Ticket information
customer_id_type	String	No	Customer identifier type
customer_id_value	String	No	Value of the customer identifier

Note: customer_id_type/customer_id_value must either both be empty or both have values
Note: If these two parameters are passed in, it means that when updating the ticket, the found customer will be associated with the ticket at the same time. If the customer cannot be found based on the information, there will be an error reminder

Data Structure of `ticket`

Parameter Name	Type	Required	Description	Constraints
subject	String	Yes	Title	Max 255 characters
content	String	No	Description
agent_id	Integer	No	Agent ID
agent_group_id	Integer	No	Agent Group ID
template_id	Integer	No	Template ID, default is the default template
status_id	Integer	No	Status ID
priority_id	Integer	No	Priority ID
follower_ids	Array	No	Follower ID array, each element is an agent ID
custom_fields	Object	No	Custom fields
tags	String	No	Tags, separated by commas

Note: There is a corresponding relationship between the agent_id (agent) and agent_group_id (agent group) parameters. If these two parameters are modified and the agent and agent group do not match, an error will occur. Data Structure of custom_fields
The attributes of custom_fields are the names of custom field identifiers;
For selection type custom fields, their value is an array of option indexes;
For text type custom fields, their value is a string in a specific format; Example:

{
    "custom_fields": {
        "TextField_1": "Plain text content", // Plain text
        "TextField_2": "Multiline text content 1\r\nMultiline text content 2", // Multiline text
        "TextField_3": "2016-08-11", // Date
        "TextField_4": "14:44:36", // Time
        "TextField_5": "2017-05-03 14:44", // Date and time
        "TextField_6": "https://www.sample.com", // Link
        "TextField_7": "13", // Positive integer
        "TextField_8": "13.33", // Numeric
        "SelectField_1": ["0"], // Dropdown list, option 1
        "SelectField_2": ["0"], // Radio button, option 1
        "SelectField_3": ["0","3"] // Checkboxes, option 1, option 4
    }
}

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
ticket	Object	Ticket information

Data Structure of `ticket`

Attribute Name	Type	Description
id	Integer	Ticket ID
field_num	String	Ticket number
subject	String	Title
content	String	Content
customer_id	Integer	Customer ID
customer_name	String	Customer name
agent_id	Integer	Responsible agent ID
agent_name	String	Agent name
agent_avatar	String	Agent avatar link
agent_group_id	Integer	Responsible agent group ID
agent_group_name	String	Responsible agent group name
template_id	Integer	Template ID
priority	String	Priority in Chinese
status	String	Status in Chinese
status_en	String	Status in English
platform_name	String	Channel in English
satisfaction	Integer	Satisfaction survey result
created_at	DateTime	Creation time
custom_fields	Object	Custom fields
organization_id	Integer	Customer's company ID
tags	Array	Tags
followers	Array	Followers, including id (followerID), nick_name (follower name), avatar (alias)
solved_deadline	DateTime	Deadline
attachments	Array	Attachments associated with the ticket, including file_name (file name), url (file URL)
im_sub_session_id	Integer	The sub_session_id of the ticket

Example

curl https://demo.udesk.cn/open_api_v1/tickets/1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X PUT \
-H 'content-type: application/json' \
-d '
{
    "ticket": {
        "subject": "Test Ticket",
        "content": "This ticket is for testing only",
        "agent_id": 1,
        "agent_group_id": 1,
        "template_id": 1,
        "status_id": 1,
        "priority_id": 1,
        "follower_ids": [
            {
                "id": 1,
                "nick_name": "Agent 1",
                "avatar": "Blue Sky"
            },
            {
                "id": 2,
                "nick_name": "Agent 2",
                "avatar": null
            }
        ],
        "attachments": [
           {
                "name": "Attachment 1",
                "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
            }
        ],
        "custom_fields": {
            "TextField_1": "Plain text content",
            "TextField_2": "Multiline text content 1\r\nMultiline text content 2",
            "TextField_3": "2016-08-11",
            "TextField_4": "14:44:36",
            "TextField_5": "2017-05-03 14:44",
            "TextField_6": "https://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": ["0"],
            "SelectField_2": ["0"],
            "SelectField_3": ["0","3"]
        },
        "tags": "Tag 1,Tag 2,Tag 3"
    },
    "customer_id_type": "customer_id",
    "customer_id_value": "1"
}'

Response

{
    "code": 1000,
    "ticket": {
        "id": 1,
        "field_num": "#1",
        "customer_id": 1,
        "customer_name": "Test User",
        "agent_id": 1,
        "agent_name": "Test Agent 1",
        "agent_avatar": "https://xxx.xxx.xxx/xxxxx1.jpg",
        "agent_group_id": 1,
        "agent_group_name": "Test Agent Group 1",
        "template_id": 1,
        "priority": "Urgent",
        "status": "Open",
        "status_id": 1,
        "status_en": "open",
        "platform_name": "api",
        "im_sub_session_id": 12,
        "subject": "Test Ticket",
        "satisfaction": null,
        "content": "This ticket is for testing only",
        "created_at": "2015-01-02T15:04:05.000+08:00",
        "custom_fields": {
            "TextField_1": "Plain text content",
            "TextField_2": "Multiline text content 1\r\nMultiline text content 2",
            "TextField_3": "2016-08-11",
            "TextField_4": "14:44:36",
            "TextField_5": "2017-05-03 14:44",
            "TextField_6": "https://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": ["0"],
            "SelectField_2": ["0"],
            "SelectField_3": ["0","3"]
        },
        "attachments": [
           {
                "name": "Attachment 1",
                "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
            }
        ],
        "tags": [
            {"id": 1, "name": "Tag 1"},
            {"id": 2, "name": "Tag 2"},
            {"id": 3, "name": "Tag 3"}
        ],
        "followers": [
            {"id": 1, "nick_name": "Test Agent 1", "avatar": "https://xxx.xxx.xxx/xxxxx1.jpg"},
            {"id": 2, "nick_name": "Test Agent 2", "avatar": "https://xxx.xxx.xxx/xxxxx2.jpg"}
        ],
        "solved_deadline": null
    }
}

Delete Ticket

This interface is used to delete a specified ticket

Request Method

DELETE /tickets/destroy_ticket

Query String Parameters

Parameter Name	Required	Type	Description
id	No	Integer	Ticket ID
num	No	String	Ticket number, e.g., num='#123'

Note:
Either id or num must be provided, and the value must not be empty, but they cannot be provided at the same time.
The value of num, such as '#848', needs to be URL encoded as %23848.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
message	String	Result explanation

Example

Request

curl https://demo.udesk.cn/open_api_v1/tickets/destroy_ticket?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&num=%23848 -X DELETE

Response

{
    "code": 1000,
    "message": "success"
}

Retrieve Ticket List

This interface is used to retrieve information about multiple tickets.

Request Method

GET /tickets

Query String Parameters

Parameter Name	Required	Type	Description
sign	Yes		Authentication signature, unless otherwise specified, required for each API call, calculation method see Authentication Method
nonce	Yes		Unique identifier for the request, a string provided by the caller, can only be used once within 15 minutes, details
sign_version	Yes		Signature algorithm version, fixed as v2, details
email	Yes		Super administrator email
type	No		Required when retrieving a list of tickets for a specific customer, values see
content	No		Required when retrieving a list of tickets for a specific customer, values see
page	No	Integer	Page number, default is 1
per_page	No	Integer	Number of records per page, default is 20, maximum is 100

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
message	String	Execution result explanation
total_pages	Integer	Total number of pages
contents	Array	Ticket list, each element see Ticket Data Structure
meta	Object	Pagination related content

Example

Request

curl https://demo.udesk.cn/open_api_v1/tickets?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response

{
    "code": 1000,
    "message": "success",
    "contents": [
        {
            "ticket": {
                "id": 1,
                "field_num": "#638",
                "subject": "Is Jane's Beauty Products authentic?",
                "content": "Yes! We guarantee that all goods sold are 100% authentic. Jane's Beauty Products, as China's leading and most user-friendly cosmetics shopping website, generates millions of orders and tens of millions of sales every month, and we highly value our commercial reputation. More information can be found in the 'Authenticity Guarantee' and 'About Us' sections.",
                "content_type": "html",
                "user_id": 1,
                "user_name": "Lucy",
                "user_email": "lucy_customer@qq.com",
                "user_cellphone": "14923491300",
                "organization_id": null,
                "assignee_id": 2,
                "assignee_name": "Tom",
                "assignee_avatar": null,
                "user_group_id": null,
                "user_group_name": null,
                "template_id": 1,
                "priority": "High",
                "status": "Open",
                "status_en": "open",
                "platform": "Email",
                "satisfaction": null,
                "custom_fields": {},
                "tags": "",
                "followers": [],
                "im_sub_session_id":125,
                "attachments": [
                  {
                    "name": "Attachment 1",
                    "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
                  },
                ],
                "creator_id": 1,
                "created_at": "2017-07-10T15:45:34.000+08:00",
                "updated_at": "2017-07-11T15:57:27.000+08:00",
                "solving_at": null,
                "resolved_at": null,
                "closed_at": null,
                "solved_deadline": null,
                "replied_at": "2017-07-11T15:57:27.000+08:00",
                "agent_replied_at": "2017-07-11T15:57:27.000+08:00",
                "customer_replied_at": "2017-07-10T15:45:33.000+08:00",
                "replied_by": "alalla"
            }
        },
        {
            "ticket": {
                "id": 2,
                "field_num": "#639",
                "subject": "How to pay? Do you support cash on delivery? Is the item in stock after being photographed?",
                "content": "Jane's Beauty Products supports Alipay accounts and quick payments, as well as savings cards/credit cards from dozens of mainstream banks in China. Ensure the security of your funds. In addition, users in the 8 districts of Beijing can choose cash on delivery. All items for sale can be purchased directly without contacting customer service.",
                "content_type": "html",
                "user_id": 2,
                "user_name": null,
                "user_email": "",
                "user_cellphone": null,
                "organization_id": null,
                "assignee_id": 2,
                "assignee_name": "Tom",
                "assignee_avatar": null,
                "user_group_id": null,
                "user_group_name": null,
                "template_id": 1,
                "priority": "High",
                "status": "Closed",
                "status_en": "closed",
                "platform": "Email",
                "satisfaction": null,
                "custom_fields": {},
                "tags": "",
                "followers": [],
                "im_sub_session_id": 125734,
                "attachments": [
                  {
                    "name": "Attachment 1",
                    "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
                  },
                ],
                "creator_id": 2,
                "created_at": "2017-07-10T15:45:34.000+08:00",
                "updated_at": "2017-07-10T15:45:34.000+08:00",
                "solving_at": "2017-07-10T15:45:34.000+08:00",
                "resolved_at": "2017-07-10T15:45:34.000+08:00",
                "closed_at": "2017-07-10T15:45:34.000+08:00",
                "solved_deadline": null,
                "replied_at": "2017-07-10T15:45:34.000+08:00",
                "agent_replied_at": null,
                "customer_replied_at": "2017-07-10T15:45:34.000+08:00",
                "replied_by": ""
            }
        },
        {
            "ticket": {
                "id": 3,
                "field_num": "#640",
                "subject": "How to use cash coupons?",
                "content": "How to use cash coupons? How to use cash coupons? How to use cash coupons?",
                "content_type": "html",
                "user_id": 2,
                "user_name": null,
                "user_email": "",
                "user_cellphone": null,
                "organization_id": null,
                "assignee_id": 2,
                "assignee_name": "Tom",
                "assignee_avatar": null,
                "user_group_id": null,
                "user_group_name": null,
                "template_id": 1,
                "priority": "Low",
                "status": "Open",
                "status_en": "open",
                "platform": "Email",
                "satisfaction": null,
                "custom_fields": {},
                "tags": "",
                "followers": [],
                "im_sub_session_id": 2357,
                "attachments": [
                  {
                    "name": "Attachment 1",
                    "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
                  },
                ],
                "creator_id": 2,
                "created_at": "2017-07-10T15:45:35.000+08:00",
                "updated_at": "2017-07-10T20:50:48.000+08:00",
                "solving_at": null,
                "resolved_at": null,
                "closed_at": null,
                "solved_deadline": null,
                "replied_at": "2017-07-10T20:50:48.000+08:00",
                "agent_replied_at": "2017-07-10T20:50:48.000+08:00",
                "customer_replied_at": "2017-07-10T15:45:35.000+08:00",
                "replied_by": "alalla"
            }
        }
    ],
    "meta": {
        "total_count": 3,
        "total_pages": 1,
        "current_page": 1,
    }
}

Retrieve Ticket Replies

This interface is used to retrieve all replies under a specific ticket.

Request Method

GET /tickets/:id/replies

URL Request Parameters

Parameter Name	Type	Description
id	Integer	Ticket ID

Query String Parameters

Parameter Name	Type	Required	Description
page	Integer	No	Page number, default is 1
per_page	Integer	No	Number of records per page, default is 20, maximum is 100

Note:
If per_page is less than 20, it will still display 20 items. If the value is greater than 100, it will display 100 items.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
replies	Array	Reply list, see structure below
meta	Object	Pagination related content

Structure of `replies`

Attribute Name	Type	Description
id	Integer	Reply ID
content	String	Reply content
content_format	String	Content type, "text"/"html"
created_at	DateTime	Creation time
function_type	String	Reply type, "internat" internal note / "external" external comment
cc	String	Carbon copy recipient email
attachments	Array	Attachment related content, see below
author	Object	Reply author information, see below

Structure of `attachments`

Attribute Name	Type	Description
url	String	Attachment link
file_name	String	Attachment name
file_size	Integer	Attachment size

Structure of `author`

Attribute Name	Type	Description
id	Integer	Reply person ID
user_type	String	Reply person type
email	String	Reply person email
avatar	String	Reply person avatar URL
nick_name	String	Reply person nickname

Example

Request

curl https://demo.udesk.cn/open_api_v1/tickets/1/replies?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response

{
 "code": 1000,
 "replies": [
    {
     "content": "Replies and replies",
     "content_format": "html",
     "created_at": "2017-09-25T16:37:30.486+08:00",
     "function_type": "internal",
     "cc": "1032750611@qq.com,2633233452@qq.com",
     "author": {
       "id": 13,
       "user_type": "agent",
       "email": "agent11@udesk.cn",
       "avatar": "",
       "nick_name": "agent11@udesk.cn"
      },
     "attachments": [
       {
          "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
          "file_name": "File for uploading 1",
          "file_size": 1222
        },
        {
          "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
          "file_name": "File for uploading 2",
          "file_size": 1222
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}

Retrieve Ticket Change Logs

This interface is used to retrieve all change logs under a specific ticket.

Request Method

GET /tickets/:id/change_logs

URL Request Parameters

Parameter Name	Type	Description
id	Integer	Ticket ID

Query String Parameters

Parameter Name	Type	Required	Description
page	Integer	No	Page number, default is 1
per_page	Integer	No	Number of records per page, default is 20, maximum is 100

Note:
If per_page is less than 20, it will still display 20 items. If the value is greater than 100, it will display 100 items.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
meta	Object	Pagination related content
change_logs	Array	Change log list, see structure below

Structure of `change_logs`

Attribute Name	Type	Description
id	Integer	Change log ID
created_at	DateTime	Creation time
author	Object	Information about the changer, see below
changes	Array	Specific change items, see below

Structure of `author`

Attribute Name	Type	Description
id	Integer	Changer's ID
user_type	String	Changer's type
email	String	Changer's email
avatar	String	Changer's avatar URL
nick_name	String	Changer's nickname

Structure of `changes`

Attribute Name	Type	Description
trigger_name	String	Ticket trigger name
field	String	Field
field_name	String	Field name
field_type	String	Field type
old_value	String	Old value
new_value	String	New value
description	String	Change description

Example

Request

curl http://demo.udesk.cn/open_api_v1/tickets/1/change_logs?email=admin@udesk.cn&nonce=9e90a68067d965faa2b8&sign=6a8db7918f757887f8e7946df4c40a646c061d3e4f96544092fc551ebb63d043&sign_version=v2&timestamp=1597909197

Response

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 3
    },
    "change_logs": [
        {
            "id": 20867,
            "created_at": "2020-07-15T16:26:52.000+08:00",
            "author": {
                "id": 1,
                "user_type": "agent",
                "email": "admin@udesk.cn",
                "avatar": "https://demo.udesk.cn/test_1571111491_788.jpg",
                "nick_name": "admin"
            },
            "changes": [
              {
                 "trigger_name": null,
                 "field": "subject",
                 "field_name": "Title",
                 "field_type": "static",
                 "old_value": "xx",
                 "new_value": "xxhaha",
                 "description": "Title: xx---->xxhaha"
              },
              {
                 "trigger_name": "test",
                 "field": "priority_id",
                 "field_name": "Priority",
                 "field_type": "static",
                 "old_value": "Urgent",
                 "new_value": "Low",
                 "description": "Priority: Urgent---->Low(Through the trigger 'test')"
              }
            ]
        }
    ]
}

Retrieve Custom Fields for Tickets (Deprecated)

This interface is used to retrieve all created custom fields for tickets.

Request Method

GET /tickets/custom_fields

Request Parameters

None

Response Data

Attribute Name	Type	Description
code	Integer	Result code, 1000 represents success
message	String	Result explanation
ticket_custom_field	Array	List of custom fields
This interface does not support cascading fields. Although it can retrieve information about cascading fields, the format of its `options` is incorrect.

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/custom_fields?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response:

{
    "code": 1000,
    "message": "success",
    "ticket_custom_fields": [
        {
            "field_name": "TextField_1",
            "field_label": "Single-line Text Field",
            "content_type": "text",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "TextField_2",
            "field_label": "Multi-line Text Field",
            "content_type": "area_text",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "TextField_3",
            "field_label": "Date Field",
            "content_type": "date",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "TextField_4",
            "field_label": "Date and Time Field",
            "content_type": "datetime",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "TextField_5",
            "field_label": "Link Field",
            "content_type": "link",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "TextField_6",
            "field_label": "Location Field",
            "content_type": "location",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "TextField_7",
            "field_label": "Time Field",
            "content_type": "time",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "TextField_8",
            "field_label": "Positive Integer Field",
            "content_type": "number",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "TextField_9",
            "field_label": "Numeric Field",
            "content_type": "numeric",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirement": false
        },
        {
            "field_name": "SelectField_1",
            "field_label": "Dropdown List Field",
            "content_type": "droplist",
            "comment": null,
            "options": [
                {
                    "0": "Dropdown Option 1"
                },
                {
                    "1": "Dropdown Option 2"
                }
            ],
            "permission": 2,
            "requirement": true
        },
        {
            "field_name": "SelectField_2",
            "field_label": "Radio Button Field",
            "content_type": "radio",
            "comment": null,
            "options": [
                {
                    "0": "Radio Button Option 1"
                },
                {
                    "1": "Radio Button Option 2"
                }
            ],
            "permission": 2,
            "requirement": true
        },
        {
            "field_name": "SelectField_3",
            "field_label": "Checkbox Field",
            "content_type": "checkbox",
            "comment": null,
            "options": [
                {
                    "0": "Checkbox Option 1"
                },
                {
                    "1": "Checkbox Option 2"
                },
                {
                    "2": "Checkbox Option 3"
                },
                {
                    "3": "Checkbox Option 4"
                }
            ],
            "permission": 2,
            "requirement": true
        }
    ]
}

Retrieve Ticket Template List

This interface is used to retrieve a list of all created ticket templates.

Request Method

GET /tickets/ticket_templates

Request Parameters

None

Response Data

Attribute Name	Type	Description
code	Integer	Result code, 1000 represents success
message	String	Result explanation
templates	Array	Details of the ticket template list, structure below
Structure of elements in `templates`
Attribute Name	Type	Description
-----------------	----------	-----------------------------
id	Integer	Template ID
name	String	Template name
description	String	Template description
custom_fields	Array	Custom fields under the template, see below
updated_at	DateTime	Last update time of the template
Structure of elements in `custom_fields`
Attribute Name	Type	Description
-----------------	---------	----------------------------
field_id	String	ID of a field in the template
field_name	String	Name of a field in the template
field_title	String	Title of a field in the template
field_type	String	Type of a field in the template
field_detail	String	Description of a field in the template

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/ticket_templates?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response:

{
    "code": 1000,
    "message": "success",
    "templates": [
        {
            "id": 1,
            "name": "default",
            "description": "",
            "updated_at": "2017-08-18T12:06:02.000+08:00",
            "custom_fields": [
                {
                    "field_id": 1,
                    "field_type": "TextField",
                    "field_name": "TextField_1",
                    "field_title": "plain text",
                    "field_detail": null
                },
                {
                    "field_id": 2,
                    "field_type": "TextField",
                    "field_name": "TextField_2",
                    "field_title": "multi-line text",
                    "field_detail": null
                },
                {
                    "field_id": 3,
                    "field_type": "TextField",
                    "field_name": "TextField_3",
                    "field_title": "date",
                    "field_detail": null
                },
                {
                    "field_id": 4,
                    "field_type": "TextField",
                    "field_name": "TextField_4",
                    "field_title": "date time",
                    "field_detail": null
                },
                {
                    "field_id": 5,
                    "field_type": "TextField",
                    "field_name": "TextField_5",
                    "field_title": "Geographical location",
                    "field_detail": null
                },
                {
                    "field_id": 6,
                    "field_type": "TextField",
                    "field_name": "TextField_6",
                    "field_title": "time",
                    "field_detail": null
                },
                {
                    "field_id": 7,
                    "field_type": "TextField",
                    "field_name": "TextField_7",
                    "field_title": "Link",
                    "field_detail": null
                },
                {
                    "field_id": 8,
                    "field_type": "TextField",
                    "field_name": "TextField_8",
                    "field_title": "Positive integer",
                    "field_detail": null
                },
                {
                    "field_id": 1,
                    "field_type": "SelectField",
                    "field_name": "SelectField_1",
                    "field_title": "drop down",
                    "field_detail": null
                },
                {
                    "field_id": 2,
                    "field_type": "SelectField",
                    "field_name": "SelectField_2",
                    "field_title": "radio",
                    "field_detail": null
                },
                {
                    "field_id": 3,
                    "field_type": "SelectField",
                    "field_name": "SelectField_3",
                    "field_title": "checkbox",
                    "field_detail": null
                },
                {
                    "field_id": 4,
                    "field_type": "SelectField",
                    "field_name": "SelectField_4",
                    "field_title": "Cascade",
                    "field_detail": null
                }
            ]
        },
        {
            "id": 30002,
            "name": "template1",
            "description": "",
            "updated_at": "2017-08-18T12:06:02.000+08:00",
            "custom_fields": [
                {
                    "field_id": 11,
                    "field_type": "TextField",
                    "field_name": "TextField_11",
                    "field_title": "plain text2",
                    "field_detail": null
                },
                {
                    "field_id": 14,
                    "field_type": "TextField",
                    "field_name": "TextField_14",
                    "field_title": "multi-line text2",
                    "field_detail": "text2"
                },
                {
                    "field_id": 18,
                    "field_type": "TextField",
                    "field_name": "TextField_18",
                    "field_title": "Link 2",
                    "field_detail": null
                },
                {
                    "field_id": 41,
                    "field_type": "TextField",
                    "field_name": "TextField_41",
                    "field_title": "Geographical location 2",
                    "field_detail": null
                },
                {
                    "field_id": 3,
                    "field_type": "SelectField",
                    "field_name": "SelectField_3",
                    "field_title": "droplist",
                    "field_detail": null
                },
                {
                    "field_id": 5,
                    "field_type": "SelectField",
                    "field_name": "SelectField_5",
                    "field_title": "checkbox",
                    "field_detail": null
                },
                {
                    "field_id": 6,
                    "field_type": "SelectField",
                    "field_name": "SelectField_6",
                    "field_title": "Cascade",
                    "field_detail": null
                }
            ]
        }
    ]
}

Retrieve Ticket Filter List

This interface is used to retrieve some or all of the created filters.

Request Method

GET /tickets/filters

Request Parameters (Request Body)

Parameter Name	Required	Type	Description	Constraints
type	No	String	It can be one of three values: agent, agent_group, all	None
id	No	Integer	The specific ID corresponding to the type; when type is all, no ID is needed	None
page	No	Integer	Page number, default is 1	None
per_page	No	Integer	Number of records per page, default is 20, maximum is 50	None

When type is all, retrieve all filters visible to all agents.
When type is agent, you can retrieve the filters visible to a specific agent by passing the ID (agent ID); without passing the ID, you can retrieve the filters visible to the agent.
When type is agent_group, you can retrieve the filters visible to a specific agent group by passing the ID (agent group ID); without passing the ID, you can retrieve the filters visible to the agent group.
The default value for type is empty, which retrieves all filters under the company.

Response Data

Attribute	Type	Description
code	Integer	Result code, 1000 represents success
message	String	Result explanation
filters	Array	Filter information, details below
meta	Object	Pagination-related content
Structure of `filters`
Attribute	Type	Description
------------------	----------	------------------------------
id	Integer	Filter ID
name	String	Filter name
description	String	Filter description
active	Boolean	Filter status, open or close
permission	String	Permission scope
permission_id	Integer	ID of the agent or agent group with permission
created_at	DateTime	Creation time
updated_at	DateTime	Last modification time

Note:
When the permission value of a filter record is all, the permission_id will be empty, indicating all agents.

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/filters?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response:

{
    "code": 1000,
    "message": "success",
    "filters": [
        {
            "id": 2,
            "name": "my unsolved ticket",
            "description": null,
            "active": true,
            "permission": "All",
            "permission_id": null,
            "created_at": "2017-07-10T15:45:32.000+08:00",
            "updated_at": "2017-08-22T09:42:10.000+08:00"
        },
        {
            "id": 4,
            "name": "all unsolved ticket",
            "description": null,
            "active": true,
            "permission": "agent",
            "permission_id": 1,
            "created_at": "2017-07-10T15:45:32.000+08:00",
            "updated_at": "2017-08-22T12:45:40.000+08:00"
        },
        {
            "id": 7,
            "name": "all urgent ticket",
            "description": null,
            "active": false,
            "permission": "agent_group",
            "permission_id": 12,
            "created_at": "2017-07-10T15:45:32.000+08:00",
            "updated_at": "2017-08-22T12:46:10.000+08:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 3
    }
}

Retrieve Tickets under a Specific Ticket Filter

This API is used to retrieve tickets under a specified ticket filter.

Request Method

GET /tickets/tickets_in_filter

Request Parameters (Query String)

Parameter Name	Type	Required	Description
filter_id	Integer	Yes	Filter ID
page	Integer	No	Page number, default is 1
per_page	Integer	No	Number of records per page, default is 20, maximum is 100

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
message	String	Execution result explanation
contents	Array	Ticket list, details in Ticket Data Structure
meta	Object	Pagination-related content

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/tickets_in_filter?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&filter_id=2

Response:

{
    "code": 1000,
    "message": "success",
    "contents": [
        {
            "ticket": {
                "id": 11,
                "field_num": "#13",
                "subject": "test",
                "content": "",
                "content_type": "html",
                "user_id": 175,
                "user_name": "test",
                "user_email": "",
                "user_cellphone": null,
                "organization_id": null,
                "assignee_id": 1,
                "assignee_name": "alalla",
                "assignee_avatar": "",
                "user_group_id": null,
                "user_group_name": null,
                "template_id": 1,
                "priority": "normal",
                "status": "open",
                "status_en": "open",
                "platform": "Manual entry",
                "satisfaction": null,
                "custom_fields": {},
                "tags": "",
                "followers": [],
                "im_sub_session_id": 3891,
                "attachments": [
                    {
                        "name": "attachment1",
                        "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
                    },
                ],
                "creator_id": 1,
                "created_at": "2017-08-18T16:59:56.000+08:00",
                "updated_at": "2017-08-18T16:59:56.000+08:00",
                "solving_at": null,
                "resolved_at": null,
                "closed_at": null,
                "solved_deadline": null,
                "replied_at": "2017-08-18T16:5956.000+08:00",
                "agent_replied_at": null,
                "customer_replied_at": "2017-08-18T16:59:56.000+08:00",
                "replied_by": "user 1"
            }
        },
        {
            "ticket": {
                "id": 12,
                "field_num": "#30",
                "subject": "demo",
                "content": "",
                "content_type": "html",
                "user_id": 174,
                "user_name": "lalllala",
                "user_email": "",
                "user_cellphone": null,
                "organization_id": null,
                "assignee_id": 1,
                "assignee_name": "alalla",
                "assignee_avatar": "",
                "user_group_id": null,
                "user_group_name": null,
                "template_id": 1,
                "priority": "normal",
                "status": "open",
                "status_en": "open",
                "platform": "Manual entry",
                "satisfaction": null,
                "custom_fields": {
                    "SelectField_3": "0",
                    "SelectField_4": "0",
                    "TextField_40": "asdfasdf dddd",
                    "TextField_3": "asdfsad "
                },
                "tags": "",
                "followers": [],
                "im_sub_session_id": 38,
                "attachments": [
                    {
                        "name": "attachment1",
                        "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
                    },
                ],
                "creator_id": 1,
                "created_at": "2017-08-18T16:55:05.000+08:00",
                "updated_at": "2017-08-18T18:45:23.000+08:00",
                "solving_at": null,
                "resolved_at": null,
                "closed_at": null,
                "solved_deadline": null,
                "replied_at": "2017-08-18T16:55:05.000+08:00",
                "agent_replied_at": null,
                "customer_replied_at": "2017-08-18T16:55:05.000+08:00",
                "replied_by": "lalllala"
            }
        },
        {
            "ticket": {
                "id": 131,
                "field_num": "#768",
                "subject": "weurouew",
                "content": "<p>asdfasdf</p>",
                "content_type": "html",
                "user_id": 143,
                "user_name": "name１０２",
                "user_email": "3468567@qq.com",
                "user_cellphone": null,
                "organization_id": null,
                "assignee_id": 1,
                "assignee_name": "alalla",
                "assignee_avatar": "",
                "user_group_id": null,
                "user_group_name": null,
                "template_id": 1,
                "priority": "normal",
                "status": "open",
                "status_en": "open",
                "platform": "Manual entry",
                "satisfaction":null,
                "custom_fields": {
                    "TextField_13": {
                        "keyword": "test"
                    },
                    "TextField_18": {
                        "keyword": "test"
                    }
                },
                "tags": "",
                "followers": [],
                "im_sub_session_id": 278,
                "attachments": [
                    {
                        "name": "attachment1",
                        "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
                    },
                ],
                "creator_id": 1,
                "created_at": "2017-08-07T23:23:37.000+08:00",
                "updated_at": "2017-08-07T23:23:37.000+08:00",
                "solving_at": null,
                "resolved_at": null,
                "closed_at": null,
                "solved_deadline": null,
                "replied_at": "2017-08-07T23:23:37.000+08:00",
                "agent_replied_at": null,
                "customer_replied_at": "2017-08-07T23:23:37.000+08:00",
                "replied_by": "name１０２"
            }
        }
    ],
    "meta": {
        "total_count": 3,
        "total_pages": 1,
        "current_page": 1
    }
}

Ticket Export

This interface is used to export a large amount of ticket information. It supports exporting tickets based on a specified filter.

Request Method

GET /tickets/export

Usage Method

Use the filter_id to call the interface. The response will include the first batch of data and a scroll_id.
After the data is processed, use the scroll_id returned from the previous call to call the interface again (note that you do not need to pass the filter_id again). The response will include the second batch of data and a new scroll_id.
Repeat step 2 until the response contains no contents. Note: For subsequent calls, you need to use the new scroll_id returned from the previous call. The scroll_id expires after 1 minute.

Request Parameters (Query String)

Parameter Name	Type	Required	Description	Constraints
filter_id	Integer	Yes	Ticket filter ID; exports the filtered results
scroll_id	String	No	ID for the next batch of data; obtained from the response of the previous call

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code; 1000 represents success
scroll_id	String	ID for the next batch of data
total	Integer	Total number of data
contents	Array	Ticket list; the same as the contents in Retrieve Tickets under a Specific Ticket Filter

Note: The maximum number of contents retrieved in one go is 1000; when the number of contents in the response is 0, it indicates the end of the export.

Example

# First call
curl https://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&filter_id=1
# Subsequent calls
curl https://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&scroll_id=DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n

Response:

{
    "code": 1000,
    "scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n",
    "total": 10000,
    "contents": [ /*...*/]
}

Upload Attachment

This interface is used to upload attachments to a specified ticket.

Request Method

POST /tickets/upload_file

Request Parameters (Query String)

Parameter Name	Required	Type	Description	Constraints
ticket_id	Yes	Integer	Ticket ID
file_name	Yes	String	File name, e.g., screenshot.gif	Max length: 255 characters
type	No	String	File type, e.g., image/gif	Max length: 255 characters

Request Parameters (Request Body)

Note:
Specify the Content-type:application/octet-stream in the request, uploading the file as a stream file in the request body.
Make sure to specify the file extension in the file_name, otherwise, the file cannot be recognized.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code; 1000 indicates success
message	Object	Result explanation, details below

message Attributes

Attribute Name	Type	Description
msg	String	Execution result explanation
url	String	Attachment URL address
attachment_id	Integer	Attachment ID

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/upload_file?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&ticket_id=1&file_name=my_picture.gif&type=image/gif -H 'Content-type:application/octet-stream' --data-binary @my_picture.gif

Response:

{
    "code": 1000,
    "message": {
        "msg": "upload Success",
        "url": "https://qn-public.udesk.cn/my_picture.gif",
        "attachment_id": 1001
    }
}

Customer Service Reply

This interface is used for customer service to reply to customers. POST /tickets/agent_reply

Request Parameters (Request Body)

Parameter Name	Type	Required	Description
id	Integer	No	Ticket ID
num	String	No	Ticket number
agent_id	Integer	Yes	Customer service ID
function_type	String	Yes	Reply type, "internal" for internal note / "external" for external comment
new_reply	String	Yes	Reply content
cc	Array	No	CC customer service emails
cc_customer	Array	No	CC customer emails
attachment_ids	Array	No	Uploaded attachment IDs

Note: id and num cannot be passed at the same time, but one of them must be passed.
In each reply, the number of CC customer service emails and CC customer emails cannot exceed ten.
If attachments are needed in the reply, please call the interface 'Ticket Reply Upload Attachment' first. You can call it multiple times to get multiple return values, which can be used as the values for the attachment_id parameter.
If the time of calling this interface exceeds two hours from the last upload attachment time, all previously uploaded attachments will be invalid and considered as having no attachments for this reply.
new_reply supports rich text. If new_reply contains image resources, please enter the image link address, such as https://mpic.tiankong.com/077/708/0777089ad18a688eee7c756a506e5f4a/640.jpg. Do not encode the image and place it after src.

Response Data

Attribute Name	Type	Description
type	String	Reply type
id	Integer	Reply ID
content	String	Reply content
content_format	String	Content type, text for normal text / html for rich text
created_at	Date	Creation time
function_type	String	Reply type, "internal" for internal note / "external" for external comment
author	Object	Information about the replier
cc	String	Nickname and email of the copied party (including customer service and customers), see example for details
attachments	Array	Information about attachments

author Attributes

Attribute Name	Type	Description
id	Integer	Replier ID
user_type	String	Identity of the replier
email	String	Replier's email
avatar	String	Replier's avatar
nick_name	String	Replier's nickname

attachments Attributes

Attribute Name	Type	Description
url	String	Attachment link
file_name	String	Attachment name
file_size	Integer	Attachment size

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/agent_reply?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb552&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X POST \
-H 'content-type:application/json' \
-d '{
    "id": 159,
    "agent_id": 13,
    "function_type": "internal",
    "attachment_ids": [209],
    "new_reply": "this is the new replay",
    "cc":  ["1032750611@qq.com","2633233452@qq.com"]
}'

Response:

{
    "code": 1000,
    "data": {
        "type": "reply",
        "data": {
            "id":10011,
            "content": "test",
            "content_format": "html",
            "created_at": "2017-09-25T16:37:30.486+08:00",
            "function_type": "internal",
            "cc": "Test Agent01 <alus@1265.com>, test customer 44 <lmy123003@sina1.com>",
            "author": {
                "id": 13,
                "user_type": "agent",
                "email": "agent11@udesk.cn",
                "avatar": null,
                "nick_name": "agent11@udesk.cn"
            },
             "attachments": [
                {
                    "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
                    "file_name": "test file1",
                    "file_size": 1222
                },
                {
                    "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
                    "file_name": "test file2",
                    "file_size": 1222
                }
            ]
        }
    }
}

Customer Reply

This interface is used for customers to reply to customer service. POST /tickets/customer_reply

Request Parameters (Request Body)

Parameter Name	Type	Required	Description
id	Integer	No	Ticket ID
num	String	No	Ticket number
new_reply	String	Yes	Reply content
content_type	String	Yes	Reply content type, html/text
attachment_ids	Array	No	Uploaded attachment IDs

Note: id and num cannot be passed at the same time, but one of them must be passed.
In each reply, the number of CC customer service emails and CC customer emails cannot exceed ten.
If attachments are needed in the reply, please call the interface 'Ticket Reply Upload Attachment' first. You can call it multiple times to get multiple return values, which can be used as the values for the attachment_id parameter.
If the time of calling this interface exceeds two hours from the last upload attachment time, all previously uploaded attachments will be invalid and considered as having no attachments for this reply.
new_reply supports rich text. If new_reply contains image resources, please enter the image link address, such as https://mpic.tiankong.com/077/708/0777089ad18a688eee7c756a506e5f4a/640.jpg. Do not encode the image and place it after src.

Response Data

The response data is the same as the customer service reply response data.

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/customer_reply?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 '{
    "id": 159,
    "content_type": "html",
    "new_reply": "<p>this is the new replay</p>",
    "attachment_ids": [201,202]
}'

Response:

{
    "code": 1000,
    "data": {
        "type": "reply",
        "data": {
            "id": 10011,
            "content": "<p>this is the new replay</p>",
            "content_format": "html",
            "created_at": "2017-09-25T17:51:44.124+08:00",
            "function_type": "external",  // Reply type: "internal" for internal note / "external" for external comment
            "author": {
                "id": 48,
                "user_type": "customer",
                "email": null,
                "avatar": null,
                "nick_name": "13000022457"
            },
            "attachments": [
                {
                    "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
                    "file_name": "test file1",
                    "file_size": 1222
                },
                {
                    "url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
                    "file_name": "test file2",
                    "file_size": 1222
                }
            ]
        }
    }
}

Upload Attachment for Ticket Reply

This interface is used exclusively for uploading attachments when replying to a ticket.

Request Method

POST /tickets/upload_file_for_reply

Request Parameters (Query String)

Parameter Name	Required	Type	Description	Constraints
ticket_id	Yes	Integer	Ticket ID
file_name	Yes	String	File name, e.g., screenshot.gif	Max length: 255 characters
type	No	String	File type, e.g., image/gif	Max length: 255 characters

Request Parameters (Request Body)

Note:
Specify the Content-type:application/octet-stream in the request, uploading the file as a stream file in the request body.
Upload one attachment at a time, and the attachment size should not exceed 20MB. You can upload multiple times; if the multiple attachments are for the same ticket reply, the total size of the attachments should not exceed 20MB.
Make sure to specify the file extension in the file_name, otherwise, the file cannot be recognized.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code; 1000 indicates success
message	Object	Result explanation, details below

message Attributes

Attribute Name	Type	Description
msg	String	Execution result explanation
url	String	Attachment URL address
attachment_id	Integer	Attachment ID
attachable_type	String	Attachable type, Reply

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/upload_file_for_reply?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&ticket_id=1&file_name=test.png&type=image/png -H 'Content-type:application/octet-stream' --data-binary @/home/udesk/Pictures/test.png

Response:

{
    "code": 1000,
    "message": {
        "msg": "upload Success",
        "url": "https://qn-public.udesk.cn/cut_my_picture.gif",
        "attachment_id": 1,
        "attachable_type": "Reply"
    }
}

Clear Attachments for Ticket Reply

This interface is used to clear all attachments in a single reply.

Request Method

POST /tickets/delete_file_for_reply

Request Parameters (Query String)

Parameter Name	Required	Type	Description
ticket_id	Yes	Integer	Ticket ID

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code; 1000 indicates success
message	String	Result explanation

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/delete_file_for_reply?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 '{
"ticket_id": 1
}'

Response:

{
    "code": 1000,
    "message": "Clear attachments successfully"
}

Retrieve Company Ticket Satisfaction Survey

GET /tickets/surveys

Request Parameters

None

Return Result

Attribute Name	Type	Description
code	Integer	Return result, 1000 indicates success
ticket_survey	Object	Satisfaction survey information
The structure of `ticket_survey` is as follows:
Attribute Name	Type	Description
----------------------	------	---------------------------
title	String	Title
enable	Boolean	Whether satisfaction survey is enabled
note	Boolean	Whether evaluation description is enabled
options	Array	Evaluation options
The structure of elements in `options` is as follows:
Attribute Name	Type	Description
----------------------	------	---------------------------
vote_number	Integer	Option number
name	String	Option description

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/surveys?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response:

{
    "code": 1000,
    "ticket_survey": {
        "title": "Ticket Satisfaction Survey",
        "enable": true,
        "note": false,
        "options": [
            {"vote_number": 1, "name": "Very Satisfied"},
            {"vote_number": 2, "name": "Satisfied"},
            {"vote_number": 3, "name": "Average"}
        ]
    }
}

Set Ticket Satisfaction

PUT /tickets/take_survey

Request Parameters

Attribute Name	Type	Required	Description
ticket_id	Integer	Yes	Ticket number
vote_number	Integer	Yes	Evaluation option number
vote_desc	String	No	Remark information for ticket satisfaction

Return Result

Attribute Name	Type	Description
code	Integer	Return result, 1000 indicates success
message	String	Result explanation

Example

Request:

curl https://demo.udesk.cn/open_api_v1/tickets/take_survey?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type:application/json' \
-d '{
"ticket_id":1,
"vote_number":10,
"vote_desc":"The service experience this time was perfect"
}'

Response:

{
"code": 1000,
"message": "success"
}

Code Error Code Description

Error Code	Message Information	exception:message Information	Description
2000	Sorry, the object ticket cannot be empty	None	Parameter {ticket} is not passed or is an empty value
	Sorry, ticket description cannot be empty	None	Parameter {content} cannot be empty
	Sorry, ticket subject cannot be empty	None	Parameter {subject} cannot be empty
	Sorry, no such customer. Please create a customer first	None	According to parameter {type}, {content_type}, customer not found
	Priority error	None	Parameter {priority_id} does not meet the required value range
	Customer service not found	None	Parameter {assignee_email} does not match any customer service
	Status error	None	The value of parameter {status} exceeds the value range
	Creator customer service not found	None	Parameter {creator_email} does not match any customer service data
	Sorry, this customer service is not in this customer service group	None	Parameter {assignee_email} is not in the customer service group corresponding to parameter {agent_group_name}
	Customer service email error	None	Parameter {assignee_email} format error
	Customer group error, customer service group not found	None	Parameter {agent_group_name} error
	Customer creation email error	None	Parameter {creator_email} format error
	Customer creation not found	None	Parameter {creator_email} does not match any data
	Time date format is incorrect	None	Custom field time parameter format error
	Sorry, you must pass id and num, and cannot be empty	None	Parameters {id} and {num} are not filled in
	Sorry, the resource does not exist	None	Parameter {id} or {num} does not match the data
	Sorry, id and num cannot be passed at the same time	None	Parameters {id} or {num} are passed at the same time
	Customer service does not exist	None	Parameter {type} is agent, parameter {id} does not match the customer service
	Customer service group does not exist	None	Parameter {type} is agent_group, parameter {id} does not match the customer service group
	Specific filter not found	None	Parameter {filter_id} does not match the filter
	ticket_id is a required field and cannot be empty	None	Parameter {ticket_id} is empty or not filled in
	file_name is a required field and cannot be empty	None	Parameter {file_name} is empty or not filled in
	Sorry, the ticket does not exist	None	Parameter {ticket_id} does not match the ticket data
	A ticket can upload up to 10 attachments	None	Attachment number exceeds 10
	Sorry, you have not uploaded attachments	None	No stream file uploaded
	A ticket associated with an attachment cannot exceed 20mb	None	The total size of attachments associated with a ticket exceeds 20mb
	Sorry, the file you uploaded exceeds 20mb	None	The size of the uploaded single stream file exceeds 20m
	Sorry, reply content new_reply is required and cannot be empty	None	Parameter {new_reply} is not filled in or is empty
	Sorry, reply type function_type is required and cannot be empty	None	Parameter {content_type} is not filled in or is empty
	Sorry, customer service id is required and cannot be empty	None	Parameter {agent_id} is empty or not filled in
	Sorry, the value of customer service id should be an integer	None	Parameter {agent_id} format error
	Sorry, the customer of the ticket does not exist	None	Parameter {id} corresponds to a ticket not associated with a customer
	Sorry, there is no attachment associated with the ticket <XXX>	None	Parameter {attachment_ids} is not empty, this ticket is not associated with "Ticket Reply Upload Attachment"
	The attachment with id <XXX> is not found	None	Parameter {attachment_ids} is not empty, and this attachment is not found in the ticket reply upload attachment
	cc is not an array format	None	Error in the format of parameter {cc}
	cc_customer is not an array format	None	Error in the format of parameter {cc_customer}
	Free companies cannot carbon copy	None	The company where this customer service is located has not paid, and this feature cannot be used
	The number of copied customers does not exceed 10	None	The length of parameter {cc_customer} exceeds 10
	The number of copied customer services does not exceed 10	None	The length of parameter {cc} exceeds 10
	No configuration for ticket satisfaction survey or ticket satisfaction survey is closed	None	This feature is not configured or closed, and it needs to be set on the web side
	Unknown error	param is missing or the value is empty: ticket	Parameter {ticket} is not filled in or is empty
		Unable to find agent	Parameter {agent_id} does not match any customer service
		The responsible group for the ticket owner is incorrect.	Parameter {agent_id} corresponding to the customer service does not match the customer service group corresponding to parameter {agent_group_id}
		Validation failed: Template "tickettemplate" does not exist	Parameter {emplate_id} does not match the data
		Priority is incorrect	Input parameter {priority_id} exceeds the value range
		Status is incorrect	Input parameter {status_id} exceeds the value range
		no implicit conversion of Array into Hash	Parameter {custom_fields} input format is incorrect
		Title is required	Parameter {subject} is an empty value
2005	No such resource found	User xxx not found	Parameter {follower_ids} does not match the data
	Couldn't find Ticket with id=XXX [WHERE `tickets`.`company_id` = ?]	Parameter {id} does not match the value
2062	Failed to get ticket information	None	Both parameter {filter_id} and {scroll_id} exist at the same time
20573	vote_number is not a positive integer	None	Parameter {vote_number} is not passed or the format is incorrect
20576	The ticket has been evaluated	None	The ticket corresponding to parameter {ticket_id} has been evaluated and cannot be evaluated repeatedly
40001	Identifier type and value must exist simultaneously or be empty simultaneously	None	None
40002	Unsupported customer_id_type	None	None
40003	No customer found based on customer_id_type and customer_id_value	None	None

Meaning of Values for Some Fields in Work Orders

Description of Pagination in Return Values

Create Work Order

Request Method

Request Parameters (Request Body)

Structure of ticket

ticket_field

Notes:

Return Data

Example

Retrieve Work Order Details

Request Method

Request Parameters (Request String)

Return Data

Data Structure of Work Order

Example

Update Ticket

Request Method

URL Request Parameters

Request Body Parameters

Data Structure of ticket

Response Data

Data Structure of ticket

Example

Delete Ticket

Request Method

Query String Parameters

Response Data

Example

Retrieve Ticket List

Request Method

Query String Parameters

Response Data

Example

Retrieve Ticket Replies

Request Method

URL Request Parameters

Query String Parameters

Response Data

Structure of replies

Structure of attachments

Structure of author

Example

Retrieve Ticket Change Logs

Request Method

URL Request Parameters

Query String Parameters

Response Data

Structure of change_logs

Structure of author

Structure of changes

Example

Retrieve Custom Fields for Tickets (Deprecated)

Request Method

Request Parameters

Response Data

Example

Retrieve Ticket Template List

Request Method

Request Parameters

Response Data

Example

Retrieve Ticket Filter List

Request Method

Request Parameters (Request Body)

Response Data

Example

Retrieve Tickets under a Specific Ticket Filter

Request Method

Request Parameters (Query String)

Response Data

Example

Ticket Export

Request Method

Usage Method

Request Parameters (Query String)

Response Data

Example

Upload Attachment

Request Method

Data Structure of `ticket`

Data Structure of `ticket`

Structure of `replies`

Structure of `attachments`

Structure of `author`

Structure of `change_logs`

Structure of `author`

Structure of `changes`