Udesk-Customer service solution leader

Retrieving Business Record Templates

This interface is used to retrieve all business record templates under a company.

Request Method

get notes/note_template

Request Parameters

None

Return Data

Attribute	Type	Description
code	Integer	Execution result code, 1000 represents success
note_template	Array	Template content, structure as follows

note_template data structure

Attribute	Type	Description
id	Integer	Business record template ID
name	String	Business record template name
desc	String	Description of the business record template
category	String	Type of the business record template
custom_fields	Array	Custom fields under the business record template
ticket_template_id	Integer	Service ticket template ID
updated_at	Datetime	Last update time of the business record template

custom_fields data structure

Attribute	Type	Description
field_id	Integer	Custom field ID
field_type	String	Type of the custom field
name	String	Name of the custom field
comment	String	Description of the custom field
is_required	Boolean	Whether it is required

Example

Request

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

Response

{
    "code": 1000,
    "note_template": [
        {
            "id": 1,
            "name": "IM Business Record",
            "desc": "Applied to customer service for organizing and recording IM conversation content",
            "category": "im",
            "ticket_template_id": 1,
            "updated_at": "2017-08-18T12:06:02.000+08:00",
            "custom_fields": [
                {
                    "field_id": 3,
                    "field_type": "TextField",
                    "name": "TextField_3",
                    "comment": null,
                    "owner": "Ticket",
                    "is_required": true
                },
                {
                    "field_id": 14,
                    "field_type": "TextField",
                    "name": "TextField_14",
                    "comment": "Developed",
                    "owner": "Ticket",
                    "is_required": false
                },
                {
                    "field_id": 40,
                    "field_type": "TextField",
                    "name": "TextField_40",
                    "comment": null,
                    "owner": "Ticket",
                    "is_required": false
                },
                {
                    "field_id": 5,
                    "field_type": "SelectField",
                    "name": "SelectField_5",
                    "comment": null,
                    "owner": "Ticket",
                    "is_required": false
                },
                {
                    "field_id": 17,
                    "field_type": "TextField",
                    "name": "TextField_17",
                    "comment": null,
                    "owner": "Ticket",
                    "is_required": false
                }
            ]
        },
        {
            "id": 2,
            "name": "Call center business records",
            "desc": "Applied to customer service for sorting and recording call center call records",
            "category": "call",
            "ticket_template_id": 1,
            "updated_at": "2017-08-18T12:06:02.000+08:00",
            "custom_fields": []
        }
    ]
}

Modify Business Record Template

This interface is used to modify the content of the business record template.

Request Method

post notes/update_note_template

Request Parameters (request body)

Attribute	Required	Type	Description
id	No	Integer	ID of the business template
category	No	Integer	Type of business template
ticket_template_id	No	Integer	ID of the ticket template
custom_fields	No	Array	Types of custom fields

Notes:
Either id or category must be provided and cannot be empty, but they cannot be provided simultaneously.
The value of category can be "im" or "call".
If only id is provided, the business record template corresponding to the id will be returned and the update time will be modified.
If only category is provided, the business record template corresponding to the category will be returned and the update time will be modified.

Example

Request

curl https://demo.udesk.cn/open_api_v1/notes/update_note_template?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":"1",
    "ticket_template_id": 30002,
    "custom_fields":  [
       {"field_id":3, "field_type":"TextField", "is_required":true},
     {"field_id":14, "field_type":"TextField", "is_required":false},
     {"field_id":40, "field_type":"TextField", "is_required":false},
     {"field_id":17, "field_type":"TextField", "is_required":false},
     {"field_id":5, "field_type":"SelectField", "is_required":false},
     {"field_id":41, "field_type":"TextField", "is_required":true}
   ]
}'

Response

{
    "code": 1000,
    "ticket_template_id":30002,
    "note_template": {
        "id": 1,
        "name": "IM Business Record",
        "desc": "Used for customer service to organize and record IM conversation content",
        "category": "im",
        "ticket_template_id": 30002,
        "custom_fields": [
            {
                "field_id": 3,
                "field_type": "TextField",
                "name": "TextField_3",
                "comment": null,
                "is_required": true
            },
            {
                "field_id": 14,
                "field_type": "TextField",
                "name": "TextField_14",
                "comment": "Developed",
                "is_required": false
            },
            {
                "field_id": 40,
                "field_type": "TextField",
                "name": "TextField_40",
                "comment": null,
                "is_required": false
            },
            {
                "field_id": 17,
                "field_type": "TextField",
                "name": "TextField_17",
                "comment": null,
                "is_required": false
            },
            {
                "field_id": 5,
                "field_type": "SelectField",
                "name": "SelectField_5",
                "comment": null,
                "is_required": false
            },
            {
                "field_id": 41,
                "field_type": "TextField",
                "name": "TextField_41",
                "comment": null,
                "is_required": true
            }
        ]
    }
}

Retrieve Business Record List

This interface is used to obtain a list of business records that meet certain conditions.

Request Method

get /notes

Request Parameters (query string)

Attribute	Required	Type	Description
start_date	No	DateTime	Start date of the business records
end_date	No	DateTime	End date of the business records
category	No	String	Type of business records, either "im" or "call"
page	No	Integer	Current page, default is 1
per_page	No	Integer	Number of records per page, range 1~50, default is 20

Notes:
Obtains business records created between start_date and end_date, defaults to the current day, can retrieve data within one year, formatted as year-month-day (2017-09-10).
If the provided page parameter format is incorrect, the parameter is not parsed, and the default value of 1 is used.

Response Data

Attribute	Type	Description
code	Integer	Execution result code, 1000 for success
note_record	Array	Business records
meta	Object	Pagination related content

Data structure of note_record

Attribute	Type	Description
id	Integer	Business record ID
content	String	Content
agent_id	Integer	Agent ID
agent_nick_name	String	Agent nickname
customer_id	Integer	Customer ID
customer_nick_name	String	Customer nickname
custom_fields	Array	Custom fields
created_at	DateTime	Creation time of the record
last_editor_id	Integer	ID of the last editor
last_editor_nick_name	String	Nickname of the last editor
category	String	Type of business record
session_id	Integer	Associated ID
session_type	String	Type of session
updated_at	DateTime	Last update time of the record

Example

Request

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

Response

{
    "code": 1000,
    "note_record": [
        {
            "id": 3,
            "content": "NULL",
            "category": "im",
            "custom_fields": {
                "SelectField_2": "1"
            },
            "created_at": "2017-01-17T14:14:55.000+08:00",
            "updated_at": "2017-01-17T14:14:55.000+08:00",
            "customer_id": 1014,
            "customer_nick_name": null,
            "agent_id": 1,
            "agent_nick_name": "alalla",
            "last_editor_id": 1,
            "last_editor_nick_name": "alalla",
            "session_id": 2,
            "session_type": "ImSubSession",
            "agent_note_template_id": 6
        },
        {
            "id": 2,
            "content": "NULL",
            "category": "im",
            "custom_fields": {
                "TextField_3": "2017-01-19"
            },
            "created_at": "2017-01-17T14:14:51.000+08:00",
            "updated_at": "2017-01-17T14:14:51.000+08:00",
            "customer_id": 1014,
            "customer_nick_name": null,
            "agent_id": 1,
            "agent_nick_name": "alalla",
            "last_editor_id": 1,
            "last_editor_nick_name": "alalla",
            "session_id": 4,
            "session_type": "ImSubSession",
            "agent_note_template_id": 3
        },
        {
            "id": 1,
            "content": "subject",
            "category": "im",
            "custom_fields": {
                "TextField_3": "2017-01-25",
                "TextField_4": "23:58:59",
                "TextField_5": "12313",
                "TextField_6": "2343243",
                "TextField_7": "https://demo.udesk.cn/entry/analysis/im/record",
                "SelectField_2": "0",
                "SelectField_3": "0,0,0",
                "SelectField_5": "0,1,2"
            },
            "created_at": "2017-01-17T14:13:41.000+08:00",
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "customer_id": 1014,
            "customer_nick_name": null,
            "agent_id": 1,
            "agent_nick_name": "alalla",
            "last_editor_id": 1,
            "last_editor_nick_name": "alalla",
            "session_id": 5,
            "session_type": "ImSubSession",
            "agent_note_template_id": 2
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_records": 3
    }
}

Retrieve a Specific Business Record Detail

This interface is used to obtain a specific business record that meets certain conditions.

Request Method

get /notes/detail

Request Parameters (query string)

Attribute	Required	Type	Description
note_id	No	Integer	ID of the business record
category	No	String	Type of the business record
session_id	No	Integer	Associated ID

Notes: There are two ways to obtain results
One is to query directly based on the provided note_id; just provide note_id.
The other is to query based on category combined with session_id; both category and session_id must be provided simultaneously and cannot be empty.
The three values cannot be provided at the same time.

Response Data

Attribute	Type	Description
code	Integer	Execution result code, 1000 for success
note_record	Object	Business record

Data structure of note_record

Attribute	Type	Description
id	Integer	Business record ID
content	String	Subject of the record
agent_id	Integer	Agent ID
agent_nick_name	String	Agent nickname
customer_id	Integer	Customer ID
customer_nick_name	String	Customer nickname
custom_fields	Array	Custom fields
created_at	DateTime	Creation time of the record
updated_at	DateTime	Last update time of the record
last_editor_id	Integer	ID of the last editor
last_editor_nick_name	String	Nickname of the last editor
category	String	Type of business record
session_id	Integer	Associated ID
session_type	String	Type of session

Example

Request

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

Response

{
    "code": 1000,
    "note_record": {
        "id": 1,
        "content": "subject",
        "category": "im",
        "custom_fields": {
            "TextField_3": "2017-01-25",
            "TextField_4": "23:58:59",
            "TextField_5": "12313",
            "TextField_6": "2343243",
            "TextField_7": "https://demo.udesk.cn/entry/analysis/im/record",
            "SelectField_2": "0",
            "SelectField_3": "0,0,0",
            "SelectField_5": "0,1,2"
        },
        "created_at": "2017-01-17T14:13:41.000+08:00",
        "updated_at": "2017-01-17T14:13:41.000+08:00",
        "customer_id": 1014,
        "customer_nick_name": null,
        "agent_id": 1,
        "agent_nick_name": "alalla",
        "last_editor_id": 1,
        "last_editor_nick_name": "alalla",
        "session_id": 5,
        "session_type": "ImSubSession",
        "agent_note_template_id": 2
    }
}

Modify Business Record

This interface is used to modify a specific business record.

Request Method

put /notes/:id

Request Parameters (request body)

Attribute	Required	Type	Description	Restrictions
note	Yes	Object	Content of the business record

The data structure of note is as follows

Attribute	Required	Type	Description
content	No	String	Subject of the record
last_editor_id	No	Integer	ID of the last editor
custom_fields	No	Object	Custom fields

Response Data

Attribute	Type	Description
code	Integer	Execution result code, 1000 for success
note_record	Object	Business record

The data structure of note_record is as follows

Attribute	Type	Description
id	Integer	Business record ID
content	String	Subject of the record
agent_id	Integer	Agent ID
agent_nick_name	String	Agent nickname
customer_id	Integer	Customer ID
customer_nick_name	String	Customer nickname
custom_fields	Array	Custom fields
created_at	DateTime	Creation time of the record
last_editor_id	Integer	ID of the last editor
last_editor_nick_name	String	Nickname of the last editor
category	String	Type of business record
session_id	Integer	Associated ID
session_type	String	Type of session

Example

Request

curl https://demo.udesk.cn/open_api_v1/notes/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 '{
  "content": "Modify Business Record",
  "custom_fields" : {
      "TextField_3": "2017-01-25",
        "TextField_4": "23:58:59",
        "TextField_5": "12313",
        "TextField_6": "2343243",
        "TextField_7": "https://demo.udesk.cn/entry/analysis/im/record",
        "SelectField_2": "0",
        "SelectField_3": "0,0,0",
        "SelectField_5": "0,1,2"
  }
}'

Response

{
    "code": 1000,
    "note_record": {
        "id": 1,
        "content": "Modify Business Record",
        "category": "im",
        "custom_fields": {
            "TextField_3": "2017-01-25",
            "TextField_4": "23:58:59",
            "TextField_5": "12313",
            "TextField_6": "2343243",
            "TextField_7": "https://demo.udesk.cn/entry/analysis/im/record",
            "SelectField_2": "0",
            "SelectField_3": "0,0,0",
            "SelectField_5": "0,1,2"
        },
        "created_at": "2017-01-17T14:13:41.000+08:00",
        "customer_id": 1014,
        "customer_nick_name": null,
        "agent_id": 1,
        "agent_nick_name": "alalla",
        "last_editor_id": 1,
        "last_editor_nick_name": "alalla",
        "session_id": 5,
        "session_type": "ImSubSession"
    }
}

Business Record Change

This interface is used to create or modify business records.

Request Method

post /notes

Request Parameters

Attribute	Required	Type	Description
category	Yes	String	Type of business record, im/call
session_id	Yes	Integer	Business record associated ID
note	Yes	Object	Content of the business record

The data structure of note is as follows

Attribute	Required	Type	Description
agent_id	Yes	Integer	Agent ID
customer_id	Yes	Integer	Customer ID
session_id	Yes	Integer	Business record corresponding session_id
session_type	Yes	String	Type corresponding to the business record
content	Yes	String	Detailed content of the business record
last_editor_id	Yes	Integer	ID of the last editor
custom_fields	Yes	Object	Custom fields

Response Data

Attribute	Type	Description
code	Integer	Execution result code, 1000 for success
note_record	Object	Business record

The data structure of note_record is as follows

Attribute	Type	Description
id	Integer	Business record ID
content	String	Subject of the record
agent_id	Integer	Agent ID
agent_nick_name	String	Agent nickname
customer_id	Integer	Customer ID
customer_nick_name	String	Customer nickname
custom_fields	Array	Custom fields
created_at	DateTime	Creation time of the record
last_editor_id	Integer	ID of the last editor
last_editor_nick_name	String	Nickname of the last editor
category	String	Type of business record
session_id	Integer	Associated ID
session_type	String	Type of session

Example

Request

curl https://demo.udesk.cn/open_api_v1/notes?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 '{
    "category": "im",
    "session_id": 5,
    "note": {
        "content": "Modify Business Record",
        "agent_id": 1,
        "customer_id": 1014,
        "session_id": 5,
        "session_type": "ImSubSession",
        "last_editor_id": 1,
        "custom_fields": {
            "TextField_3": "2017-01-25",
            "TextField_4": "23:58:59",
            "TextField_5": "12313",
            "TextField_6": "2343243",
            "TextField_7": "https://demo.udesk.cn/entry/analysis/im/record",
            "SelectField_2": "0",
            "SelectField_3": "0,0,0",
            "SelectField_5": "0,1,2"
        }
    }
}'

Response

{
    "code": 1000,
    "note_record": {
        "id": 1,
        "content": "Modify Business Record",
        "category": "im",
        "custom_fields": {
            "TextField_3": "2017-01-25",
            "TextField_4": "23:58:59",
            "TextField_5": "12313",
            "TextField_6": "2343243",
            "TextField_7": "https://demo.udesk.cn/entry/analysis/im/record",
            "SelectField_2": "0",
            "SelectField_3": "0,0,0",
            "SelectField_5": "0,1,2"
        },
        "created_at": "2017-01-17T14:13:41.000+08:00",
        "customer_id": 1014,
        "customer_nick_name": null,
        "agent_id": 1,
        "agent_nick_name": "alalla",
        "last_editor_id": 1,
        "last_editor_nick_name": "alalla",
        "session_id": 5,
        "session_type": "ImSubSession"
    }
}

Error Codes

Error Code	Message	Exception: Message	Description
2000	Unknown error	Sorry, id and category must be provided with one of them and the value cannot be empty	id and category must be provided with one of them and the value cannot be empty
	Unknown error	Verification failed: Ticket template cannot be empty	Ticket template is empty or does not exist
	Unknown error	per_page's range is 1~50	per_page's range is 1~50
	Unknown error	Sorry, the resource does not exist	Cannot find the resource corresponding to the provided id, it may not exist or the format of the id is incorrect
	Unknown error	category, session_id must be provided simultaneously and cannot be empty	category, session_id must be provided simultaneously and cannot be empty
	Unknown error	unexist params type	The value range of category is im or call
	Unknown error	The customer corresponding to last_editor_id does not exist	The customer corresponding to last_editor_id does not exist
2005	Resource not found	ActiveRecord::RecordNotFound	Cannot find the resource corresponding to the provided id, it may not exist or the format of the id is incorrect
	Resource not found	Couldn't find ImSubSession with 'id'=xxx WHERE `im_sub_sessions`.`company_id` = ?	Cannot find the resource corresponding to category and session_id
2015	Non-administrator cannot perform operations	Non-administrator cannot perform operations	The email used to call the interface must be an administrator email, non-administrators cannot perform operations
2059	Open API signature is incorrect	Open API signature is incorrect	Open API signature is incorrect, refer to the Authentication section of the documentation for details

Retrieving Business Record Templates

Request Method

Request Parameters

Return Data

Example

Request

Response

Modify Business Record Template

Request Method

Request Parameters (request body)

Example

Request

Response

Retrieve Business Record List

Request Method

Request Parameters (query string)

Response Data

Example

Request

Response

Retrieve a Specific Business Record Detail

Request Method

Request Parameters (query string)

Response Data

Example

Request

Response

Modify Business Record

Request Method

Request Parameters (request body)

The data structure of note is as follows

Response Data

The data structure of note_record is as follows

Example

Request

Response

Business Record Change

Request Method

Request Parameters

Response Data

Example

Request

Response

Error Codes

Products

Solutions

Resources