Udesk-Customer service solution leader

Knowledge Base Category Interface

knowledge_type values

English Name
question
useful_expression
useful_link
attachment

Create Different Knowledge Base Categories

This interface is used to create different types of knowledge base categories.

Request Method

POST /knowledge_catalogs

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
knowledge_catalog	Object	Yes	Knowledge base parameters	None

The structure of knowledge_catalog is as follows:

Parameter Name	Type	Required	Description	Restrictions
name	String	Yes	Name of the knowledge base	No more than 255 characters
knowledge_type_name	String	Yes	English name from knowledge_type	None
parent_id	Integer	No	ID of the parent category	None
agent_id	Integer	Yes	Customer service ID	None

Notes:

knowledge_type_name: Only the four values from knowledge_type are supported.
agent_id: The value is the customer service ID or 0, where 0 represents the administrator. The owner of the newly created category is the customer service corresponding to the agent_id. Other ordinary customer services do not have permission to operate this category. If the value of agent_id is 0, the administrator is the owner of the new category.
parent_id: If the parameter does not include parent_id, a top-level category is created by default; if a subcategory needs to be created, the parameter must be passed, and its value is the ID of the parent category. In the example, write any integer for the value of parent_id, but it cannot be empty.

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
name	String	Name of the new category
id	Integer	ID of the new category

Example

Request

curl https://demo.udesk.cn/open_api_v1/knowledge_catalogs?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X POST \
-H 'content-type: appliacation/json' \
-d '
{
    "knowledge_catalog": {
        "knowledge_type_name": "question",
        "name": "Question library 1",
        "agent_id":0,
        "parent_id": ""
    }
}
'

Result

{
    "code": 1000,
    "id": 22,
    "name": "Question library 1"
}

Modify Different Knowledge Base Categories

This interface is used to modify existing different types of knowledge base categories.

Request Method

PUT /knowledge_catalogs/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Category ID	None

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
knowledge_catalog	Object	Yes	Knowledge base parameters	None

The structure of knowledge_catalog is as follows:

Parameter Name	Type	Required	Description	Restrictions
name	String	Yes	Name of the knowledge base	No more than 255 characters
agent_id	Integer	Yes	Customer service ID	None

Notes:

agent_id: Specific customer service ID or 0, where 0 represents the administrator.
Only the owner of the category has the permission to make changes. If the customer service corresponding to the agent_id passed in the parameter is not the same person as the owner of the category, the modification cannot be made.

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
name	String	Name of the new category
id	Integer	ID of the modified category

Example

Request

curl https://demo.udesk.cn/open_api_v1/knowledge_catalogs/11?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: appliacation/json' \
-d '
{
    "knowledge_catalog": {
        "name": "Frequently used links",
        "agent_id": 0
    }
}
'

Result

{
    "code": 1000,
    "id": 11,
    "name": "Frequently used links"
}

Delete Different Knowledge Base Categories

This interface is used to delete existing different types of knowledge base categories.

Request Method

DELETE /knowledge_catalogs/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Category ID	None

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
knowledge_catalog	Object	Yes	Knowledge base parameters	None

The structure of knowledge_catalog is as follows:

Parameter Name	Type	Required	Description	Restrictions
agent_id	Integer	Yes	Customer service ID	None

Notes:

agent_id: Specific customer service ID or 0, where 0 represents the administrator.
Only the owner of the category has the permission to delete. If the customer service corresponding to the agent_id passed in the parameter is not the same person as the owner of the category, the deletion cannot be made.

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
id	Integer	ID of the deleted category
message	String	Information about deleting the category

Example

Request

curl https://demo.udesk.cn/open_api_v1/knowledge_catalogs/19?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X DELETE \
-H 'content-type: appliacation/json' \
-d '
{
    "knowledge_catalog": {
        "agent_id":"0"
    }
}
'

Result

{
    "code": 1000,
    "message": "Category delete success",
    "id": "19"
}

Get Different Knowledge Base Category Lists

This interface is used to get existing different types of knowledge base category lists.

Request Method

GET /knowledge_catalogs

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
knowledge_type_name	String	Yes	English name from knowledge_type	None
agent_id	Integer	Yes	Customer service ID, default is the administrator	None

Notes:

agent_id: Specific customer service ID or 0, where 0 represents the administrator.
If the value of agent_id is a valid customer service ID, it will get the categories of a certain type of knowledge base for that customer service;
If the value of agent_id is 0, it will get the categories of a certain type of knowledge base for the administrator;

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
catalogs	Array	Category list

The structure of catalogs is as follows:

Attribute Name	Type	Description
name	String	Name of the category
id	Integer	ID of the category
parent_id	Integer	Parent ID of the category
children	Object	Subcategories of the category

Example

Request

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

Result

{
    "code": 1000,
    "catalogs": [
        {
            "id": 4,
            "parent_id": 0,
            "name": "Common phrases 1"
        },
        {
            "id": 5,
            "parent_id": 0,
            "name": "Common phrases 2",
            "children": [
                {
                    "id": 6,
                    "parent_id": 5,
                    "name": "Common phrases 1-1"
                }
            ]
        }
    ]
}

Useful Expressions Interface

Get Useful Expressions List

This interface is used to get all or specified category useful expressions for a specific customer service.

Request Method

GET /useful_expressions

Request Parameters (Query String)

Parameter Name	Type	Required	Description
catalog_id	Integer	Yes	Useful expression category id
agent_id	Integer	Yes	ID of the owner of the category
page	Integer	No	Page number, starting from 1, default is 1
per_page	Integer	No	Number per page, default is 20, maximum is 100

Notes:

catalog_id: Specific category id or 0, where 0 represents all.
agent_id: Specific customer service ID or 0, where 0 represents the administrator.

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
useful_expressions	Array	Useful expressions list
meta	Object	Pagination related content, see Common Data

The structure of useful_expressions is as follows:

Attribute Name	Type	Description
id	Integer	Useful expression id
content	String	Useful expression content
catalog_id	Integer	Useful expression category id

Example

Request

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

Response

{
    "code": 1000,
    "useful_expressions": [
        {
            "id": 1,
            "content": "content1",
            "catalog_id": 4
        },
        {
            "id": 2,
            "content": "content2",
            "catalog_id": 5
        },
        {
            "id": 3,
            "content": "content2",
            "catalog_id": 6
        },
        {
            "id": 4,
            "content": "content4",
            "catalog_id": 6
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 4
    }
}

Update Useful Expression

This interface is used to modify the content of a specific useful expression.

Request Method

PUT /useful_expressions/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Useful expression id

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
content	String	Yes	Useful expression content
agent_id	Integer	Yes	Creator's ID of the useful expression

Notes:

The value of agent_id is a specific customer service ID or 0, where 0 represents the administrator.

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
id	Integer	Useful expression id
content	String	Useful expression content

Example

Request

curl https://demo.udesk.cn/open_api_v1/useful_expressions/4?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: appliacation/json' \
-d '
{
  "content": "content12",
  "agent_id": 0
}
'

Response

{
    "code": 1000,
    "id": 4,
    "content": "content12",
    "catalog_id": 6
}

Add Useful Expression

This interface is used to create a new useful expression under a specific category of a specific customer service.

Request Method

POST /useful_expressions

Request Parameters (Request Body)

Parameter Name	Type	Required	Description
content	String	Yes	Useful expression content
catalog_id	Integer	Yes	Useful expression category id
agent_id	Integer	Yes	Creator's ID of the useful expression

Notes:

catalog_id: Specific category id.
agent_id: Specific customer service ID or 0, where 0 represents the administrator.

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
id	Integer	Useful expression id
content	String	Useful expression content
catalog_id	Integer	Useful expression category id

Example

Request

curl https://demo.udesk.cn/open_api_v1/useful_expressions?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X POST \
-H 'content-type: appliacation/json' \
-d '
{
  "content": "kakkakakakakakakaka",
  "agent_id": 0,
  "catalog_id": 6
}
'

Response

{
    "code": 1000,
    "id": 4,
    "content": "kakkakakakakakakaka",
    "catalog_id": 6
}

Delete Useful Expression

This interface is used to delete a specific useful expression.

Request Method

DELETE /useful_expressions/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Useful expression id

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
agent_id	Integer	Yes	Creator's ID of the useful expression

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
id	Integer	Useful expression id
message	String	Result description

Example

Request

curl https://demo.udesk.cn/open_api_v1/useful_expressions/4?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X DELETE \
-H 'content-type: application/json' \
-d '
{
"agent_id": 0
}
'

Response

{
    "code": 1000,
    "message": "Useful expression deleted successfully",
    "id": 4
}

Common Link Interfaces

Obtain a List of Common Links

This interface is used to retrieve all or specified category common links under a certain customer service.

Request Method

GET /useful_links

Request Parameters (Query String)

Parameter Name	Type	Required	Description
catalog_id	Integer	Yes	Common link category id
agent_id	Integer	Yes	The id of the owner of the common link category
page	Integer	No	Page number, starting from 1, default is 1
per_page	Integer	No	Number of items per page, default is 20, maximum is 100

Notes:

catalog_id: The specific category id or 0, 0 represents all
agent_id: The specific customer service id or 0, 0 represents the administrator

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
useful_links	Array	Common link list
meta	Object	Pagination related content, see Common Data

Data Structure of useful_links

Attribute Name	Type	Description
id	Integer	Common link id
name	String	Common link name
url	String	Common link address
catalog_id	Integer	Common link category id

Example

Request

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

Response

{
    "code": 1000,
    "useful_links": [
        {
            "id": 6,
            "name": "Link ６",
            "url": "https://www.baidu1.com",
            "catalog_id": 11
        },
        {
            "id": 8,
            "name": "Link ８",
            "url": "https://www.baidu1.com",
            "catalog_id": 11
        },
        {
            "id": 9,
            "name": "Link ９",
            "url": "https://www.baidu1.com",
            "catalog_id": 11
        },
        {
            "id": 10,
            "name": "Link １０",
            "url": "https://www.baidu1.com",
            "catalog_id": 11
        },
        {
            "id": 11,
            "name": "Link １１",
            "url": "https://www.baidu1.com",
            "catalog_id": 11
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 5
    }
}

Update Common Link

This interface is used to modify a specific common link.

Request Method

PUT /useful_links/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Common link id

Request Parameters (Request Body)

Parameter Name	Type	Required	Description
name	String	No	Common link content
url	String	No	Common link address
agent_id	Integer	Yes	The id of the creator of the common link

Notes:

The value of agent_id is the specific customer service id or 0, 0 represents the administrator
In a single request, the common link name and common link address cannot be empty at the same time

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
id	Integer	Common link id
name	String	Common link name
url	String	Common link address
catalog_id	Integer	Common link category id

Example

Request

curl https://demo.udesk.cn/open_api_v1/useful_links/12?email=admin@udesk.cn&timestamp=149447&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: appliacation/json' \
-d '
{
"name": "",
"url": "https://www.bai.com",
"agent_id": 4
}'

Response

{
    "code": 1000,
    "id": 12,
    "name": "name",
    "url": "https://www.bai.com",
    "catalog_id": 12
}

Add Common Link

This interface is used to create a new common link under a certain customer service's common link category.

Request Method

POST /useful_links

Request Parameters (Request Body)

Parameter Name	Type	Required	Description
name	String	Yes	Common link name
url	String	Yes	Common link address
catalog_id	Integer	Yes	Common link category id
agent_id	Integer	Yes	The id of the creator of the common link

Notes:

catalog_id: The specific category id, there is no category with id 0
agent_id: The specific customer service id or 0, 0 represents the administrator

Return Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
id	Integer	Common link id

Example

Request

curl https://demo.udesk.cn/open_api_v1/useful_expressions?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X POST \
-H 'content-type: appliacation/json' \
-d '
{
  "name": "Link １0",
  "url": "https://www.baidu1.com",
  "catalog_id": 12,
  "agent_id": 4
}
'

Response

{
    "code": 1000,
    "id": 12,
    "name": "Link １0",
    "url": "https://www.baidu1.com",
    "catalog_id": 12
}

Delete Common Link

This interface is used to delete a specific common link.

Request Method

DELETE /useful_links/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Common link id

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
agent_id	Integer	Yes	The id of the creator of the common link

Return Data

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

Example

Request

curl https://demo.udesk.cn/open_api_v1/useful_expressions/7?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X DELETE \
-H 'content-type: appliacation/json' \
-d '
{
  "agent_id": 4
}
'

Response

{
    "code": 1000,
    "id": "7",
    "message": "Common link deleted successfully"
}

Knowledge Base API

Questions are time-sensitive. When lasts is true, the values of last_min and last_max are meaningless; when lasts is false, the values of last_min and last_max are meaningful.

Get Knowledge Base Questions List

This interface is used to get the list of knowledge base questions under a certain customer service or specified category.

Request Method

GET /knowledge_questions

Request Parameters (Query String)

Parameter Name	Type	Required	Description
catalog_id	Int	Yes	Category ID
agent_id	Int	Yes	Owner ID
page	Int	No	Page number, starts from 1, default is 1
per_page	Int	No	Number per page, default is 20, max is 100

Notes:

catalog_id: Specific category ID or 0 or -1, 0 represents all, -1 represents uncategorized.
agent_id: Specific customer service ID or 0, 0 represents the administrator.

Return Data

Attribute Name	Type	Description
code	Int	Execution result code, 1000 means success
knowledge_questions	Array	Knowledge base questions list
meta	Object	Pagination related content, see Common Data

Data structure of knowledge_questions

Attribute Name	Type	Description
id	Int	Knowledge base question ID
title	String	Knowledge base question name
content	String	Knowledge base question answer
content_type	String	Knowledge base question answer type
catalog_id	Int	Category ID
updated_at	DateTime	Last update time of the question
lasts	Boolean	Whether the question is permanently valid
last_min	DateTime	Lower limit of question validity
last_max	DateTime	Upper limit of question validity

Example

Request

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

Response

{
    "code": 1000,
    "knowledge_questions": [
        {
            "id": 1,
            "title": "Question 1",
            "content": "question content",
            "content_type": "text",
            "lasts": true,
            "catalog_id": null,
            "updated_at": "2018-03-22T11:29:59.000+08:00",
            "last_min": null,
            "last_max": null
        },
        {
            "id": 3,
            "title": "demo title",
            "content": "demo content",
            "content_type": "text",
            "lasts": true,
            "catalog_id": 17,
            "updated_at": "2018-03-22T18:35:02.000+08:00",
            "last_min": "2018-03-31",
            "last_max": "2018-04-03"
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 2
    }
}

Update Knowledge Base

This interface is used to modify a specific knowledge base question.

Request Method

PUT /knowledge_questions/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Int	Yes	Question ID

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
question	Object	Yes	Specific question values

Data structure of question

Parameter Name	Type	Required	Description
agent_id	Int	Yes	Creator's ID
content	String	No	Question answer
title	String	No	Question name
content_type	String	No	Question answer type
lasts	Boolean	Yes	Is the question permanently valid
last_min	DateTime	No	Lower limit of question validity
last_max	DateTime	No	Upper limit of question validity

Notes:

The value of agent_id is a specific customer service ID or 0, where 0 represents the administrator.
If the value of content/title/content_type is "" or null, it is considered not to be modified.
The value of content_type is text/html.
When the value of lasts is true, the values of last_min and last_max are not saved.

Return Data

Attribute Name	Type	Description
code	Int	Execution result code, 1000 means success
id	Int	Knowledge base ID
title	String	Knowledge base question name
content_type	String	Knowledge base question content type
content	String	Knowledge base question content
lasts	Boolean	Is the knowledge base question permanently valid
last_min	DateTime	Lower limit of knowledge base question validity
last_max	DateTime	Upper limit of knowledge base question validity

Example

Request

curl https://demo.udesk.cn/open_api_v1/knowledge_questions/8?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: appliacation/json' \
-d '
{
    "question": {
        "agent_id": 0,
        "content": "asasasaasasadasass",
        "title": "",
        "content_type": "",
        "lasts": false,
        "last_min": "2018-03-31",
        "last_max": "2018-04-03"
    }
}
'

Response

{
    "code": 1000,
    "id": 8,
    "title": "title5",
    "content": "asasasaasasadasass",
    "content_type": "html",
    "catalog_id": null,
    "lasts": false,
    "last_min": "2018-03-31",
    "last_max": "2018-04-03"
}

Add Knowledge Base Question

This interface is used to create a new knowledge base question under a certain customer service's category.

Request Method

POST /knowledge_questions

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
question	Object	Yes	Specific question values

Data structure of question

Parameter Name	Type	Required	Description
agent_id	Int	Yes	Creator's ID
content	String	Yes	Question answer
title	String	Yes	Question name
content_type	String	Yes	Question answer type
catalog_id	Int	Yes	Category ID
lasts	Boolean	Yes	Is the question permanently valid
last_min	DateTime	No	Lower limit of question validity
last_max	DateTime	No	Upper limit of question validity

Notes:

catalog_id: Specific category ID or 0 or -1, 0 represents all, -1 represents uncategorized.
agent_id: Specific customer service ID or 0, where 0 represents the administrator.

Return Data

Attribute Name	Type	Description
code	Int	Execution result code, 1000 means success
id	Int	Knowledge base ID

Example

Request

curl https://demo.udesk.cn/open_api_v1/useful_expressions?email=admin@udesk.cn&timestamp=1494474404&sign&sign_version=v2 \
-X POST \
-H 'content-type: appliacation/json' \
-d '
{
"question": {
"agent_id": 0,
"content": "asasasas",
"title": "title1",
"content_type": "html",
"catalog_id":0,
"lasts": true
}
}
'

Response

{
    "code": 1000,
    "id": 8,
    "title": "title5",
    "content": "asasasas",
    "content_type": "html",
    "catalog_id": null,
    "lasts": true,
    "last_min": null,
    "last_max": null
}

Delete Knowledge Base Question

This interface is used to delete a specific knowledge base question.

Request Method

DELETE /knowledge_questions/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Int	Yes	Question ID

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
agent_id	Int	Yes	Creator's ID

Return Data

Attribute Name	Type	Description
code	Int	Execution result code, 1000 means success
id	Int	Knowledge base ID
message	String	Success message

Example

Request

curl https://demo.udesk.cn/open_api_v1/knowledge_questions/8?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X DELETE \
-H 'content-type: appliacation/json' \
-d '
{
  "agent_id": 0
}
'

Response

{
    "code": 1000,
    "id": "8",
    "message": "question delete success"
}

Attachment Library API

Get Attachment Library List

This interface is used to get the list of attachments under a certain customer service or specified category.

Request Method

GET /knowledge_attachments

Request Parameters (Query String)

Parameter Name	Type	Required	Description
catalog_id	Int	Yes	Category ID
agent_id	Int	Yes	Owner ID
page	Int	No	Page number, starts from 1, default is 1
per_page	Int	No	Number per page, default is 20, max is 100

Notes:

catalog_id: Specific category ID or 0, 0 represents all.
agent_id: Specific customer service ID or 0, 0 represents the administrator.

Return Data

Attribute Name	Type	Description
code	Int	Execution result code, 1000 means success
knowledge_attachments	Array	Attachment list
meta	Object	Pagination related content, see Common Data

Data structure of knowledge_attachments

Attribute Name	Type	Description
id	Int	Attachment ID
file_name	String	Attachment name
file_type	String	Attachment type
file_size	String	Attachment size
file_url	String	Attachment URL
catalog_id	Int	Category ID of attachment

Example

Request

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

Response

{
    "code": 1000,
    "knowledge_attachments": [
        {
            "id": 1,
            "catalog_id": 9,
            "file_name": "JPG.JPG",
            "file_type": "image/jpeg",
            "file_size": null,
            "file_url": "https://qn-public.udesk.cn/1472632419-JPG.JPG"
        },
        {
            "id": 2,
            "catalog_id": 10,
            "file_name": "JPG.JPG",
            "file_type": "image/jpeg",
            "file_size": null,
            "file_url": "https://qn-public.udesk.cn/JPG.JPG"
        },
        {
            "id": 3,
            "catalog_id": null,
            "file_name": "file.docx",
            "file_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "file_size": "11858",
            "file_url": "https://qn-public.udesk.cn/Fs65I3NAYnqt_URMYQB8NAwerWI3"
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 3
    }
}

Re-Upload Attachment

This interface is used to modify a specific attachment.

Request Method

PUT /knowledge_attachments/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description
id	Int	Yes	Attachment ID
file_name	String	Yes	Attachment file name
type	String	Yes	Attachment file type
agent_id	Int	Yes	Attachment creator's ID

Notes:

agent_id's value is a specific customer service ID or 0, where 0 represents the administrator.
In the request, specify Content-type:application/octet-stream, upload the file as a stream file in the request body.
Please ensure the correctness of the file type type, otherwise the file cannot be recognized.

Return Data

Attribute Name	Type	Description
id	Int	Attachment ID
file_name	String	Attachment name
file_type	String	Attachment type
file_size	String	Attachment size
file_url	String	Attachment URL
catalog_id	Int	Category ID of attachment

Example

Request

curl https://demo.udesk.cn/open_api_v1/knowledge_attachments?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&file_name=aaa&type=jpg&agent_id=0&catalog_id=10 \
-X PUT \
-H 'content-type: appliacation/json' \
-d '
'

Response

{
    "code": 1000,
    "id": 5,
    "catalog_id": 10,
    "file_name": "9747.jpg_wh300.jpg",
    "file_type": "jpg",
    "file_size": 79044,
    "file_url": "https://qn-public.udesk.cn/Fk8NQDfDUqbImbZvD37VVDejCNfv"
}

Add New Attachment

This interface is used to create a new attachment under a certain customer service's category.

Request Method

POST /knowledge_attachments

Request Parameters (Request URL)

Parameter Name	Type	Required	Description
file_name	String	Yes	Attachment name
type	String	Yes	Attachment file type
catalog_id	Int	Yes	Attachment category ID
agent_id	Int	Yes	Attachment creator's ID

Notes:

catalog_id: Specific category ID.
agent_id: Specific customer service ID or 0, where 0 represents the administrator.
In the request, specify Content-type:application/octet-stream, upload the file as a stream file in the request body.
Please ensure the correctness of the file type type, otherwise the file cannot be recognized.

Return Data

Attribute Name	Type	Description
id	Int	Attachment ID
file_name	String	Attachment name
file_type	String	Attachment type
file_size	String	Attachment size
file_url	String	Attachment URL
catalog_id	Int	Category ID of attachment

Example

Request

curl https://demo.udesk.cn/open_api_v1/knowledge_attachments?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&file_name=aaa&type=jpg&agent_id=0&catalog_id=10 \
-X POST \
-H 'content-type: appliacation/json' \
-d '
'

Response

{
    "code": 1000,
    "id": 4,
    "catalog_id": 10,
    "file_name": "9747.jpg_wh300.jpg",
    "file_type": "jpg",
    "file_size": 79044,
    "file_url": "https://qn-public.udesk.cn/Fk8NQDfDUqbImbZvD37VVDejCNfv"
}

Delete Attachment

This interface is used to delete a specific attachment.

Request Method

DELETE /knowledge_attachments/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Int	Yes	Attachment ID
agent_id	Int	Yes	Attachment creator's ID

Return Data

Attribute Name	Type	Description
code	Int	Execution result code, 1000 means success
id	Int	Attachment ID
message	String	Result description

Example

Request

curl https://demo.udesk.cn/open_api_v1/knowledge_attachments/4111?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X DELETE \
-H 'content-type: appliacation/json' \
-d '
{
  "agent_id": 12
}
'

Response

{
    "code": 1000,
    "id": "4111",
    "message": "Attachment delete success"
}

Error Code Description

Error Code	Message Information	Exception:message Information	Description
2000	`agent_id` is a required field		The `agent_id` field was not filled in the parameters.
	`agent_id` must be an integer		The `agent_id` parameter is not an integer.
	The category does not exist		There is no category with the id `\{catelog_id\}`.
	The category does not exist under the agent's name		The category with id `{catelog_id}` does not belong to the agent with id `{agent_id}` and cannot be modified.
	`catalog_id` is a required field		The `{catelog_id}` parameter cannot be empty.
	`catalog_id` must be an integer		The value of `{catelog_id}` in the parameters must be an integer.
	The resource was not found		No data was found with the corresponding id.
	The link category does not exist under the agent's name		The frequently used link category with id `{catelog_id}` does not belong to the agent with id `{agent_id}`.
	Unknown error		An unknown error occurred.
		`knowledge_type_name` value is incorrect	The value of parameter `{knowledge_type_name}` is incorrect.
		Verification failed: Name cannot be an empty string	The value of parameter `{name}` cannot be empty.
		Verification failed: Parent does not belong to the same category	The category with id `{parent_id}` was not found under the `{knowledge_type_name}` type.
		Cannot create a category as there is content under the parent category	The category with id `{parent_id}` is not a leaf node (has other data).
		A maximum of four levels of categories can be created	The category with id `{parent_id}` is a fourth-level category (the knowledge base category allows a maximum of 4 levels).
		Verification failed: Name is already in use	There is a subcategory with the same name as `{name}` under the category with id `{parent_id}`.
		The administrator's existing category does not have a subcategory with id `{parent_id}`	The category with id `{parent_id}` does not exist.
		param is missing or the value is empty: `knowledge_catalog`	The parameter is missing the object `{knowledge_catalog}`.
		The content `content` of the frequently used phrase cannot be empty	The value of `content` in the parameters cannot be empty.
		You have not set the content to be modified	When modifying the frequently used link, at least one of the `name` or `url` parameters must have a value.
		The name `name` of the frequently used link is a required field	The value of `name` in the parameters cannot be empty.
		The URL `url` of the frequently used link is a required field	The value of `url` in the parameters cannot be empty.
		param is missing or the value is empty: `question`	The parameter is missing the `question` object.
		The value of `content_type` is incorrect	The value of the `content_type` parameter can only be `text` or `html`.
		The validity period `lasts` of the question cannot be empty	The value of `lasts` in the parameters cannot be empty, it must be `true/false`.
		The format of `last_min` is incorrect	When the value of `lasts` is `false`, the value of `last_min` must follow the date format and cannot be empty.
		The format of `last_max` is incorrect	When the value of `lasts` is `false`, the value of `last_max` must follow the date format and cannot be empty.
		`last_max` cannot be less than or equal to `last_min`	When the value of `lasts` is `false`, the value of `last_max` must be less than or equal to the value of `last_min`.
		`content` cannot be empty	The value of `content` in the parameters cannot be empty.
		`title` cannot be empty	The value of `title`in the parameters cannot be empty.
		`content_type` cannot be empty	The value of `content_type` in the parameters cannot be empty.
		The value of the validity period `lasts` of the question is incorrect	The value of `lasts` in the parameters cannot be empty, it must be `true/false`.
		The upper and lower limits of the validity period of the question cannot be empty	The values of `last_min` and `last_max` in the parameters cannot be empty.
		`file_name` is a required field and cannot be empty	The value of `file_name` in the parameters cannot be empty.
		`type` is a required field and cannot be empty	The value of `type` in the parameters cannot be empty.
2005	The resource was not found	ActiveRecord::RecordNotFound	The parameter `\{id\}` did not match any data.