Explanation of some field values

Corresponding values of employee type (profile)

Value
all
im
call
ticket
dial

ucpapp_subaccount

Attribute Name	Type	Description
number	String	SIP account
password	String	SIP password
lang value range

Value	Meaning
zh-cn	Simplified Chinese
en-us	American English

Get the list of customer service representatives

This interface is used to obtain multiple customer service information at one time

Request Method

GET /agents

Request Parameters (Query String)

Parameter Name	Required	Type	Description	Limitations
page	No	Integer	Page number, starting from 1, default is 1
per_page	No	Integer	Number of items per page, default is 20, maximum is 100
with_disabled	No	String	Whether to include disabled customer service representatives, default is false (does not include disabled customer service representatives)	true or false

Returned Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 means success
meta	Object	Pagination information, see Common Data for details
agents	Array	List of customer service representatives, see customer service data for the description of each customer service representative

Customer Service Data

Attribute Name	Type	Description
id	Integer	Unique identifier
email	String	Email address
nick_name	String	Name
profile	String	Employee type
aliase	String	External nickname
cellphone	String	Mobile phone number
role_name	String	Role
duty	String	Employee position
im_ability_value	Integer	Conversation skill value
user_group_ids	Array	List of customer service group IDs
password	String	Call center SIP account information
number	String	Call center SIP account information
avatar	String	Avatar
work_id	String	Work number
departments	Object	Department to which it belongs, including id (department ID) and name (department name), see example for details
agent_callout_display_number	String	Outbound display number
disable_status	String	Status
availability	String	Whether to receive automatic assignment of work orders
im_welcomes	String	Welcome message
lang	String	Language preference

Example

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

Returns

{
"code": 1000,
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1
},
"agents": [
{
"id": 1,
"email": "agent1@sample.com",
"nick_name": "Test Customer Service 1",
"profile": "im",
"aliase": null,
"cellphone": "13300000001",
"role_name": "agent",
"duty": null,
"im_ability_value": 10,
"user_group_ids": [1,2],
"number": "100000000",
"password": "xxxxxxxx",
"avatar": null,
"work_id": "",
"departments": [
{
"id": 1,
"name": "demo"
}
],
"agent_callout_display_number": "10000000000",
"disable_status": "enable",
"availability": true,
"im_welcomes": null,
"lang": null
}
]
}

---

Get Customer Service Details

This interface is used to obtain customer service information under specified conditions.

Request Method

GET /agents/get_agent

Request Parameters (Query String)

Parameter Name	Type	Required	Description	Restrictions
type	string	Yes	Condition type, see below for details
content	string	Yes	Condition content

Condition Type

Value	Corresponding content meaning
id	Customer service ID
email	Customer service email

Returned Data

Attribute Name	Type	Description
code	int	Execution result code, 1000 means success
agent	object	Customer service information

Customer Service Data

Attribute Name	Type	Description
id	int	Unique identifier
email	string	Email address
nick_name	string	Name
profile	string	Employee type
aliase	string	External nickname
cellphone	string	Mobile phone number
role_name	string	Role
duty	string	Employee position
user_group_ids	array	List of customer service group IDs
im_ability_value	int	Conversation skill value
work_id	string	Job number
disable_status	string	Enable or disable status (enable/disable)
availability	boolean	Whether to accept automatic work order distribution
password	string	Call center SIP account information
number	string	Call center SIP account information
avatar	string	Avatar
departments	object	Department to which it belongs
agent_callout_display_number	string	Outbound display number
im_welcomes	string	Welcome message
lang	string	Language preference
user_groups	array	Information of the customer service group to which it belongs, see example
agent_roles	array	Information of the role to which it belongs, see example

Example

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

Returns

{
"code": 1000,
"agent": {
"id": 1,
"email": "agent1@sample.com",
"nick_name": "Test Customer Service 1",
"profile": "im",
"aliase": null,
"cellphone": "13300000001",
"role_name": "agent",
"duty": null,
"user_group_ids": [1,2],
"im_ability_value": 10,
"work_id": "123",
"disable_status": "enable",
"availability": true,
"number": "100000000",
"password": "xxxxxxxx",
"avatar": null,
"lang": "zh-cn",
"im_welcomes": null,
"user_groups": [
{
"id": 1,
"name": "Test Group"
}
],
"agent_roles": [
{
"id": 11,
"name": "Customer Service"
}
],
"departments": [
{
"id": 1,
"name": "Customer Service Group 1"
}
],
"agent_callout_display_number": "100000000"
}
}

---

Create Customer Service

This interface is used to create customer service.

Request Method

POST /agents

Request Parameters (request body)

Parameter Name	Type	Required	Description	Restrictions
agent	object	Yes	Customer service information, see below
Structure of agent

Parameter Name	Type	Required	Description	Restrictions	Default Value
email	string	Yes	Email address, used as account	Not more than 255 characters
password	string	Yes	Password	Not more than 255 characters
agent_role_ids	array	Yes	Role ID, comma-separated numbers, maximum length of array is 10
user_group_ids	array	Yes	Employee group ID, comma-separated numbers, maximum length of array is 10
department_ids	array	Yes	Department ID, comma-separated numbers, maximum length of array is 10
im_ability_value	int	Yes	Conversation skill value
nick_name	string	No	Name	Not more than 255 characters	null
aliase	string	No	Nickname	Not more than 255 characters	null
cellphone	string	No	Phone number	Not more than 255 characters	null
profile	string	No	Employee type	Not more than 255 characters	im
duty	string	No	Position	Not more than 255 characters	null
im_welcomes	string	No	Welcome message		null
availability	boolean	No	Whether to accept automatic work order distribution		true
avatar	string	No	Avatar URL		null
work_id	string	No	Job number		null
callout_number_id	int	No	Outbound display number ID		null
lang	string	No	Language preference		null
Note:

• The value of agent_role_ids can be obtained in the role list, and non-company agent_role_id will be removed in the request.
• The value of user_group_ids can be obtained in the customer service group list, and non-company user_group_id will be removed in the request.
• The value of department_ids can be obtained in the department list, and non-company department_id will be removed in the request.
• The value of callout_number_id can be obtained in the call center interface-Get call center trunk number list.

Returned Data

Attribute Name	Type	Description
code	int	Execution result code, 1000 means success
agent_id	int	ID of the newly created customer service

Example

Request

curl https://demo.udesk.cn/open_api_v1/agents?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 '
{
"agent":{
"email": "agent_001@udesk.cn",
"password": "agent12345",
"nick_name": "agent_001",
"aliase": "agent_001",
"cellphone": "13123456789",
"profile": "all",
"agent_role_ids": [1,2],
"user_group_ids": [2],
"im_ability_value": 1,
"department_ids": [1,3],
"duty": "Department Manager",
"im_welcomes": "Welcome",
"availability": false,
"avatar": "http://attachments.gfan.com/forum/attachments2/201302/03/11281446n2st1its4152n5.jpg",
"lang": "en-us"
}
}'

Returns

{
"code": 1000,
"agent_id": 1
}

Modify Customer Service Agent

This interface is used to modify the basic information of an existing customer service agent.

Request

PUT agents/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Customer service agent ID
with_disabled	String	No	Whether to include disabled agents

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
agent	Object	Yes	Customer service information, details below
Agent Structure

Parameter Name	Type	Required	Description	Restrictions
email	String	No	Account	No more than 255 characters
password	String	No	Password	No more than 255 characters
nick_name	String	No	Name	No more than 255 characters
aliase	String	No	Nickname	No more than 255 characters
cellphone	String	No	Phone number	No more than 255 characters
profile	String	No	Employee type, details below	No more than 255 characters
agent_role_ids	Array	No	Role IDs
user_group_ids	Array	No	Employee group IDs
im_ability_value	Integer	No	Chat skill value
department_ids	Array	No	Department IDs
duty	String	No	Position	No more than 255 characters
im_welcomes	String	No	Welcome message
availability	Boolean	No	Whether to accept automatic ticket assignment
avatar	String	No	Avatar URL
work_id	String	No	Employee ID
disable_status	String	No	Enable or disable status	Enable or disable
callout_number_id	Integer	No	Outbound calling display number ID
lang	String	No	Language preference
Note: Only modify the parameters provided in the request, do not modify what is not included.

Response Data

Property Name	Type	Description
code	Integer	Execution result code, 1000 represents success
agent	Object	Details below
Agent Structure

Property Name	Type	Description
id	Integer	Customer service agent ID
email	String	Account
nick_name	String	Name
aliase	String	Nickname
cellphone	String	Phone number
profile	String	Employee type
agent_roles	Array	Roles
user_groups	Array	Employee groups
im_ability_value	Integer	Chat skill value
departments	Array	Departments
duty	String	Position
im_welcomes	String	Welcome message
availability	Boolean	Whether to accept automatic ticket assignment
avatar	String	Avatar URL
lang	String	Language preference
agent_callout_display_number	String	Outbound calling display number
disable_status	String	Enable or disable status
work_id	String	Employee ID
number	String	IP phone number
password	String	IP phone password

Example

Request

curl https://demo.udesk.cn/open_api_v1/agents/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 '{
    "agent":{
        "email": "agent_0010@udesk.cn",
        "nick_name": "agent_0010",
        "aliase": "agent_0010",
        "cellphone": "15834234893",
        "profile": "all",
        "work_id": null,
        "disable_status": "enable",
        "number": "97425540622337",
        "password": "6ab7d5b8d8472241",
        "agent_role_ids" :[1,4],
        "user_group_ids" :[2],
        "im_ability_value" : 1,
        "department_ids" :[1,3],
        "duty": "Department Manager",
        "im_welcomes": "",
        "availability": true,
        "avatar": ""
    }
}'

Response

{
    "code": 1000,
    "agent":{
        "id": 1,
        "email": "agent_0010@udesk.cn",
        "nick_name": "agent_0010",
        "aliase": "agent_0010",
        "cellphone": "15834234893",
        "profile": "all",
        "agent_roles": [{"id":1,"name":"role 1"}, {"id":4,"name":"role 4"}],
        "user_groups": [{"id":2,"name":"Agent Group 1"}],
        "im_ability_value": 1,
        "departments": [{"id":1,"name":"Department 1"}, {"id":3,"name":"Department 3"}],
        "duty": "Department Manager",
        "im_welcomes": "",
        "availability": true,
        "lang": "zh-cn",
        "avatar": "",
        "work_id": "1231",
        "disable_status": "enable",
        "number": "98151643491111",
        "password": "23fece86b5841f17"
    }
}

Delete Customer Service Agent

This interface is used to delete a specified customer service agent.

Request

DELETE agents/:id

Request Parameters (URL)

Parameter Name	Type	Required	Description	Restrictions
id	Integer	Yes	Customer service agent ID

Request Parameters (Request Body)

Parameter Name	Type	Required	Description	Restrictions
owner_group_id	Integer	Yes	Customer service group ID
owner_id	Integer	No	Customer service agent ID

Note: After deleting a customer service agent, the customers responsible for by this agent will be transferred to another customer service group/agent. The provided owner_id must be within the owner_group_id. If no owner_group_id and owner_id are provided in the request, the responsible agent/group for the customers of this agent will be set to empty. If the owner_group_id is empty in the request, the responsible agent/group for the customers of this agent will be set to empty.

Response Data

Property Name	Type	Description
code	Integer	Execution result code, 1000 represents success
message	String	Execution result description

Example

Request

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

Response

{
    "code": 1000,
    "message": "The customer service agent with ID 1 has been successfully deleted"
}

Get Role List

This interface is used to obtain the role list information under the current company.

Request Method

GET /agent_roles

Request Parameters

None

Response Data

Property Name	Type	Description
code	Integer	Execution result code, 1000 represents success
agent_roles	Array	Details below
agent_roles Structure

Parameter Name	Type	Description
id	Integer	Role ID
name	String	Role name
description	String	Role description

Example

Request

curl https://demo.udesk.cn/open_api_v1/agent_roles?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X GET \
-H 'content-type: application/json' \

Response

{
    "code": 1000,
    "agent_roles": [
        {"id": 1, "name": "Role 1", "description": ""},
        {"id": 2, "name": "Role 2", "description": ""},
        {"id": 3, "name": "Role 3", "description": ""}
    ]
}

---

Error Code Description

Error Code	Message Information	Exception:message Information	Description
2000	The resource does not exist, please check the input parameters	None	When a custom field is set as required, the parameter {custom_fields} is not filled in or does not meet the requirements
	XXX is required, XXX is required	None	Required parameter {XXX} is not filled in
	The employee type cannot be assigned this permission	None	Parameter {profile} is not filled in
	The email has been occupied	None	Parameter {email} is already in use
	The callout_number_id value is invalid	None	Parameter {callout_number_id} is not within the valid range
	The current type of employee has reached the limit	None	The number of customer service agents corresponding to parameter {profile} has reached the company's limit
	Verification failed: the password must be different from the email address	None	Parameter {password} is the same as parameter {email}
	The customer service agent has responsible customers and cannot be deleted	None	The agent specified by parameter {id} has responsible tickets and customers
	Unknown error	param is missing or the value is empty: agent	Required parameter {agent} is not filled in
		comparison of Fixnum with nil failed	The input parameter is out of range or the data was not found
2005	The resource does not exist, please check the input parameters	None	Parameters {type} and {content} did not match any data
	No such resource was found	None	The request parameter {id} is incorrect, no matching data was found
11006	None	None	The employee IM is online, cannot be updated
11007	None	None	The employee has some IM sessions that are not closed, cannot be updated