定制机票Statuses
定制机票Statuses indicate the state of a ticket. Each custom ticket status must belong to a status category.
定制机票Statuses and Status Categories
Each custom ticket status must belong to one of five ticket status categories. The status categories correspond to the existing five legacy ticket statuses:
- "new"
- "open"
- "pending"
- "hold"
- "solved"
In the case of tickets with the legacy Closed status, Zendesk automation will use a custom ticket status belonging to the "solved" status category.
Each status category has one default custom ticket status which must always be active. The only exception is the "hold" category when the category is disabled. The "new" status category has only one custom ticket status and is the default. The "new" category's one and only custom ticket status can never be deactivated.
Changing a custom ticket status from default to non-default is not allowed. The only way to change the default custom ticket status is by using theBulk Update Default Custom Ticket Status API.
定制机票Status limits
There are limits for creating custom ticket status.
- 300 custom ticket status per account
- 100 custom ticket status per status category
JSON format
定制机票Statuses are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
active | boolean | false | false | If true, the custom status is set to active, If false, the custom status is set to inactive |
agent_label | string | false | true | The label displayed to agents. Maximum length is 48 characters |
created_at | string | true | false | The date and time the custom ticket status was created |
default | boolean | false | false | If true, the custom status is set to default. If false, the custom status is set to non-default |
description | string | false | false | The description of when the user should select this custom ticket status |
end_user_description | string | false | false | The description displayed to end users |
end_user_label | string | false | false | The label displayed to end users. Maximum length is 48 characters |
id | integer | true | false | Automatically assigned when the custom ticket status is created |
raw_agent_label | string | true | false | The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "agent_label" value. SeeDynamic Content Items |
raw_description | string | true | false | The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "description" value.Dynamic Content Items |
raw_end_user_description | string | true | false | The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "end_user_description" value. SeeDynamic Content Items |
raw_end_user_label | string | true | false | The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "end_user_label" value. SeeDynamic Content Items |
status_category | string | false | true | The status category the custom ticket status belongs to. Allowed values are "new", "open", "pending", "hold", or "solved". |
updated_at | string | true | false | The date and time the custom ticket status was last updated |
List Custom Ticket Statuses
GET /api/v2/custom_statuses
Lists all undeleted custom ticket statuses for the account. No pagination is provided.
You can't have more than 300 custom ticket statuses at a time.
Allowed For
- End Users
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
active | boolean | 查询 | false | If true, show only active custom ticket statuses. If false, show only inactive custom ticket statuses. If the filter is not used, show all custom ticket statuses |
default | boolean | 查询 | false | If true, show only default custom ticket statuses. If false, show only non-default custom ticket statuses. If the filter is not used, show all custom ticket statuses |
status_categories | string | 查询 | false | Filter the list of custom ticket statuses by a comma-separated list of status categories |
Code Samples
curl
curlhttps://{subdomain}.zendesk.com/api/v2/custom_statuses.json\
-v -u{email_address}:{password}
Go
import(
"fmt"
"io"
"net/http"
)
funcmain(){
url:="https://example.zendesk.com/api/v2/custom_statuses?active=&default=&status_categories="
method:="GET"
req,err:=http.NewRequest(method,url,nil)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Basic
" )// Base64 encoded "username:password"client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Nodejs
varaxios=require('axios');
varconfig={
method:'GET',
url:'https://example.zendesk.com/api/v2/custom_statuses',
headers:{
'Content-Type':'application/json',
'Authorization':'Basic
' ,// Base64 encoded "username:password"},
params:{
'active':'',
'default':'',
'status_categories':'',
},
};
axios(config)
.then(function(response){
console.log(JSON.stringify(response.data));
})
.catch(function(error){
console.log(error);
});
Python
importrequests
url="https://example.zendesk.com/api/v2/custom_statuses?active=&default=&status_categories="
headers={
"Content-Type":"application/json",
}
response=requests.request(
"GET",
url,
auth=('
' ,'' ),headers=headers
)
print(response.text)
Ruby
require"net/http"
uri=URI("https://example.zendesk.com/api/v2/custom_statuses")
uri.query=URI.encode_www_form("active":"","default":"","status_categories":"")
request=Net::HTTP::Get.new(uri,"Content-Type":"application/json")
request.basic_auth"username","password"
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
{
"custom_statuses":[
{
"active":true,
"agent_label":"Responding quickly",
"created_at":"2021-07-20T22:55:29Z",
"default":false,
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing",
"id":35436,
"raw_agent_label":"Responding quickly",
"raw_description":"Customer needs a response quickly",
"raw_end_user_description":“您的机票是回应”,
"raw_end_user_label":"Urgent processing",
"status_category":"open",
"updated_at":"2021-07-20T22:55:29Z"
}
]
}
Show Custom Ticket Status
GET /api/v2/custom_statuses/{custom_status_id}
Returns the custom ticket status object.
Allowed For
- End Users
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
custom_status_id | integer | Path | true | The id of the custom status |
Code Samples
curl
curlhttps://{subdomain}.zendesk.com/api/v2/custom_status/{custom_status_id}.json\
-v -u{email_address}:{password}
Go
import(
"fmt"
"io"
"net/http"
)
funcmain(){
url:="https://example.zendesk.com/api/v2/custom_statuses/1234567"
method:="GET"
req,err:=http.NewRequest(method,url,nil)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Basic
" )// Base64 encoded "username:password"client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Nodejs
varaxios=require('axios');
varconfig={
method:'GET',
url:'https://example.zendesk.com/api/v2/custom_statuses/1234567',
headers:{
'Content-Type':'application/json',
'Authorization':'Basic
' ,// Base64 encoded "username:password"},
};
axios(config)
.then(function(response){
console.log(JSON.stringify(response.data));
})
.catch(function(error){
console.log(error);
});
Python
importrequests
url="https://example.zendesk.com/api/v2/custom_statuses/1234567"
headers={
"Content-Type":"application/json",
}
response=requests.request(
"GET",
url,
auth=('
' ,'' ),headers=headers
)
print(response.text)
Ruby
require"net/http"
uri=URI("https://example.zendesk.com/api/v2/custom_statuses/1234567")
request=Net::HTTP::Get.new(uri,"Content-Type":"application/json")
request.basic_auth"username","password"
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
{
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"created_at":"2021-07-20T22:55:29Z",
"default":false,
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing",
"id":35436,
"raw_agent_label":"Responding quickly",
"raw_description":"Customer needs a response quickly",
"raw_end_user_description":“您的机票是回应”,
"raw_end_user_label":"Urgent processing",
"status_category":"open",
"updated_at":"2021-07-20T22:55:29Z"
}
}
Create Custom Ticket Status
POST /api/v2/custom_statuses
Takes acustom_status
object that specifies the custom ticket status properties to create.
Allowed For
- Admins
Request body format
Name | Type | Mandatory | Description |
---|---|---|---|
active | boolean | false | If true, the custom status is set to active. If false, the custom status is set to inactive |
agent_label | string | true | The dynamic content placeholder or the label displayed to agents. Maximum length for displayed label is 48 characters |
description | string | false | The description of when the user should select this custom ticket status |
end_user_description | false | false | The description displayed to end users |
end_user_label | string | false | The dynamic content placeholder or the label displayed to end users. Maximum length for displayed label is 48 characters |
status_category | string | true | The status category the custom status belongs to. Allowed values are "new", "open", "pending", "hold", or "solved" |
Example body
{
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing",
"status_category":"open"
}
}
Code Samples
curl
curlhttps://{subdomain}.zendesk.com/api/v2/custom_statuses.json\
-d{" custom_status ":{”status_category": "open", "agent_label": "Responding quickly", "end_user_label": "Urgent processing", "description": "Responding quickly", "end_user_description": "Responding quickly"}}'\
-H"Content-Type: application/json"-v -u{email_address}:{password}-X POST
Go
import(
"fmt"
"io"
"net/http"
"strings"
)
funcmain(){
url:="https://example.zendesk.com/api/v2/custom_statuses"
method:="POST"
payload:=strings.NewReader(`{
"custom_status": {
"active": true,
"agent_label": "Responding quickly",
"description": "Customer needs a response quickly",
"end_user_description": "Your ticket is being responded to",
"end_user_label": "Urgent processing",
"status_category": "open"
}
}`)
req,err:=http.NewRequest(method,url,payload)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Basic
" )// Base64 encoded "username:password"client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Nodejs
varaxios=require('axios');
vardata=JSON.stringify({
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing",
"status_category":"open"
}
});
varconfig={
method:'POST',
url:'https://example.zendesk.com/api/v2/custom_statuses',
headers:{
'Content-Type':'application/json',
'Authorization':'Basic
' ,// Base64 encoded "username:password"},
data:data,
};
axios(config)
.then(function(response){
console.log(JSON.stringify(response.data));
})
.catch(function(error){
console.log(error);
});
Python
importrequests
importjson
url="https://example.zendesk.com/api/v2/custom_statuses"
payload=json.loads("""{
"custom_status": {
"active": true,
"agent_label": "Responding quickly",
"description": "Customer needs a response quickly",
"end_user_description": "Your ticket is being responded to",
"end_user_label": "Urgent processing",
"status_category": "open"
}
}""")
headers={
"Content-Type":"application/json",
}
response=requests.request(
"POST",
url,
auth=('
' ,'' ),headers=headers,
json=payload
)
print(response.text)
Ruby
require"net/http"
uri=URI("https://example.zendesk.com/api/v2/custom_statuses")
request=Net::HTTP::Post.new(uri,"Content-Type":"application/json")
request.body=%q({
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing",
"status_category":"open"
}
})
request.basic_auth"username","password"
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|
http.request(request)
end
Example response(s)
201 Created
// Status 201 Created
{
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"created_at":"2021-07-20T22:55:29Z",
"default":false,
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing",
"id":35436,
"raw_agent_label":"Responding quickly",
"raw_description":"Customer needs a response quickly",
"raw_end_user_description":“您的机票是回应”,
"raw_end_user_label":"Urgent processing",
"status_category":"open",
"updated_at":"2021-07-20T22:55:29Z"
}
}
Update Custom Ticket Status
PUT /api/v2/custom_statuses/{custom_status_id}
Takes acustom_status
object that specifies the properties to update.
Allowed For
- Admins
Request body format
Name | Type | Description |
---|---|---|
active | boolean | If true, the custom status is set to active. If false, the custom status is set to inactive |
agent_label | string | The dynamic content placeholder or the label displayed to agents. Maximum length for displayed label is 48 characters |
description | string | The description of when the user should select this custom ticket status |
end_user_description | string | The description displayed to end users |
end_user_label | string | The dynamic content placeholder or the label displayed to end users. Maximum length for displayed label is 48 characters |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
custom_status_id | integer | Path | true | The id of the custom status |
Example body
{
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing"
}
}
Code Samples
curl
curlhttps://{subdomain}.zendesk.com/api/v2/custom_statuses/{custom_status_id}.json\
-d'{"custom_status": {"agent_label": "{{dc.quick}}", "end_user_label": "{{dc.urgent}}"}}'\
-H"Content-Type: application/json"-v -u{email_address}:{password}-X PUT
Go
import(
"fmt"
"io"
"net/http"
"strings"
)
funcmain(){
url:="https://example.zendesk.com/api/v2/custom_statuses/1234567"
method:="PUT"
payload:=strings.NewReader(`{
"custom_status": {
"active": true,
"agent_label": "Responding quickly",
"description": "Customer needs a response quickly",
"end_user_description": "Your ticket is being responded to",
"end_user_label": "Urgent processing"
}
}`)
req,err:=http.NewRequest(method,url,payload)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Basic
" )// Base64 encoded "username:password"client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Nodejs
varaxios=require('axios');
vardata=JSON.stringify({
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing"
}
});
varconfig={
method:'PUT',
url:'https://example.zendesk.com/api/v2/custom_statuses/1234567',
headers:{
'Content-Type':'application/json',
'Authorization':'Basic
' ,// Base64 encoded "username:password"},
data:data,
};
axios(config)
.then(function(response){
console.log(JSON.stringify(response.data));
})
.catch(function(error){
console.log(error);
});
Python
importrequests
importjson
url="https://example.zendesk.com/api/v2/custom_statuses/1234567"
payload=json.loads("""{
"custom_status": {
"active": true,
"agent_label": "Responding quickly",
"description": "Customer needs a response quickly",
"end_user_description": "Your ticket is being responded to",
"end_user_label": "Urgent processing"
}
}""")
headers={
"Content-Type":"application/json",
}
response=requests.request(
"PUT",
url,
auth=('
' ,'' ),headers=headers,
json=payload
)
print(response.text)
Ruby
require"net/http"
uri=URI("https://example.zendesk.com/api/v2/custom_statuses/1234567")
request=Net::HTTP::Put.new(uri,"Content-Type":"application/json")
request.body=%q({
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing"
}
})
request.basic_auth"username","password"
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
{
"custom_status":{
"active":true,
"agent_label":"Responding quickly",
"created_at":"2021-07-20T22:55:29Z",
"default":false,
"description":"Customer needs a response quickly",
"end_user_description":“您的机票是回应”,
"end_user_label":"Urgent processing",
"id":35436,
"raw_agent_label":"Responding quickly",
"raw_description":"Customer needs a response quickly",
"raw_end_user_description":“您的机票是回应”,
"raw_end_user_label":"Urgent processing",
"status_category":"open",
"updated_at":"2021-07-20T22:55:29Z"
}
}
Bulk Update Default Custom Ticket Status
PUT /api/v2/custom_status/default
Updates the default values for many custom ticket statuses at once.
Allowed For
- Admins
Request body format
Name | Type | Description |
---|---|---|
ids | string | The comma-separated list of custom status ids to be set as default for their category |
Example body
{
"ids":"1234567,1234577"
}
Code Samples
curl
curlhttps://{subdomain}.zendesk.com/api/v2/custom_status/default.json\
-d'{"ids": "1234567,1234577"}'\
-H"Content-Type: application/json"-v -u{email_address}:{password}-X PUT
Go
import(
"fmt"
"io"
"net/http"
"strings"
)
funcmain(){
url:="https://example.zendesk.com/api/v2/custom_status/default"
method:="PUT"
payload:=strings.NewReader(`{
"ids": "1234567,1234577"
}`)
req,err:=http.NewRequest(method,url,payload)
iferr!=nil{
fmt.Println(err)
return
}
req.Header.Add("Content-Type","application/json")
req.Header.Add("Authorization","Basic
" )// Base64 encoded "username:password"client:=&http.Client{}
res,err:=client.Do(req)
iferr!=nil{
fmt.Println(err)
return
}
deferres.Body.Close()
body,err:=io.ReadAll(res.Body)
iferr!=nil{
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Nodejs
varaxios=require('axios');
vardata=JSON.stringify({
"ids":"1234567,1234577"
});
varconfig={
method:'PUT',
url:'https://example.zendesk.com/api/v2/custom_status/default',
headers:{
'Content-Type':'application/json',
'Authorization':'Basic
' ,// Base64 encoded "username:password"},
data:data,
};
axios(config)
.then(function(response){
console.log(JSON.stringify(response.data));
})
.catch(function(error){
console.log(error);
});
Python
importrequests
importjson
url="https://example.zendesk.com/api/v2/custom_status/default"
payload=json.loads("""{
"ids": "1234567,1234577"
}""")
headers={
"Content-Type":"application/json",
}
response=requests.request(
"PUT",
url,
auth=('
' ,'' ),headers=headers,
json=payload
)
print(response.text)
Ruby
require"net/http"
uri=URI("https://example.zendesk.com/api/v2/custom_status/default")
request=Net::HTTP::Put.new(uri,"Content-Type":"application/json")
request.body=%q({
"ids":"1234567,1234577"
})
request.basic_auth"username","password"
response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
{}