Unified statuses that are available for an account. This includes all default and custom unified statuses.

JSON format

Unified agent statuses are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
customarraytruefalseArray of Custom Unified Status objects
defaultarraytruefalseArray of Default Unified Status objects
linksobjecttruefalsePagination links for the previous and next pages of data
metaobjecttruefalseOther non-standard information about unified agent statuses response

Get Unified Agent Statuses

  • GET /api/v2/agent_availabilities/agent_statuses

Returns the account's default and custom unified statuses. Unified agent statuses are returned in lexicographical order and are paginated. No other methods of sorting are supported.

With no query parameters, the initial page returned displays both default and custom unified statuses for the agent. To navigate to a different page of statuses, use the pagination links provided. The pagination links use the page[before] or page[after] parameters. The page[before] and page[after]parameters can't be used together in a single request.

Inferred status color

Unified statuses have an inferred color. The inferred status color is used for determining the displayed color of the custom status in the unified status switcher and around the user profile icon in the Agent Workspace. The unified status switcher is only visible when Omnichannel Routing is turned on.

The inferred status color is calculated based on the per channel status mapping in the following order of priority:

  • Priority 1: If there is at least 1 "ONLINE" channel, inferred status color will be "ONLINE".

  • Priority 2: If 2 or more channels are mapped to the same status, then the inferred status color will be set accordingly (e.g [ "AWAY", "AWAY", "OFFLINE" ] is inferred as "AWAY")

  • Priority 3: If none of the above conditions are satisfied, the inferred status color will be "OFFLINE" by default (e.g [ "AWAY", "TRANSFERS_ONLY", "OFFLINE" ] is inferred as "OFFLINE")

Allowed For

  • Admins

Parameters

NameTypeInRequiredDescription
page[after]integerQueryfalseThe cursor returned in the next link in the preceding response
page[before]integerQueryfalseThe cursor returned in the prev link in the preceding response
page[size]integerQueryfalseThe maximum number of custom unified statuses returned per page. If not specified, defaults to 20

Code Samples

Curl
curl -v -u {email_address}/token:{api_token} \  'https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses?page%5Bafter%5D=203&page%5Bsize%5D=5' \  --header 'Zendesk-Api-Version: 2023-02-01' \  --header 'Content-Type: application/json'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses?page[after]=1234&page[before]=1234&page[size]=88"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Zendesk-Api-Version", "2023-02-01")	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses")		.newBuilder()		.addQueryParameter("page[after]", "1234")		.addQueryParameter("page[before]", "1234")		.addQueryParameter("page[size]", "88");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Zendesk-Api-Version", "2023-02-01")		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses',  headers: {	'Zendesk-Api-Version': '2023-02-01',	'Content-Type': 'application/json',  },  params: {    'page[after]': '1234',    'page[before]': '1234',    'page[size]': '88',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses?page[after]=1234&page[before]=1234&page[size]=88"headers = {	"Zendesk-Api-Version": "2023-02-01",	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses")uri.query = URI.encode_www_form("page[after]": "1234", "page[before]": "1234", "page[size]": "88")request = Net::HTTP::Get.new(uri, "Zendesk-Api-Version": "2023-02-01", "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "custom": [    {      "attributes": {        "channels": {          "messaging": "away",          "support": "online",          "talk": "away"        },        "description": "Used while attending meetings",        "group_ids": [          123456,          234567        ],        "name": "In a meeting"      },      "id": 205,      "type": "agent_status",      "updated_at": "2021-07-21T17:32:28Z"    },    {      "attributes": {        "channels": {          "messaging": "away",          "support": "online",          "talk": "away"        },        "description": "Used while on a call",        "group_ids": [],        "name": "Custom Status 2"      },      "id": 206,      "type": "agent_status",      "updated_at": "2021-07-21T17:32:28Z"    }  ],  "default": [    {      "attributes": {        "description": "Can't receive work",        "name": "offline"      },      "id": 2,      "type": "agent_status"    },    {      "attributes": {        "description": "Can receive work",        "name": "online"      },      "id": 3,      "type": "agent_status"    }  ],  "links": {    "next": "https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses?page%5Bafter%5D=206",    "prev": "https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses?page%5Bbefore%5D=205"  },  "meta": {    "has_more": true  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "InvalidPaginationParameter",      "title": "page[size] must be a positive integer <= 100; got 0"    }  ]}
401 Unauthorized
// Status 401 Unauthorized
{  "errors": [    {      "code": "Unauthorized",      "title": "Unauthorized"    }  ]}
403 Forbidden
// Status 403 Forbidden
{  "errors": [    {      "code": "InvalidPermissions",      "title": "Forbidden"    }  ]}
406 Not Acceptable
// Status 406 Not Acceptable
{  "errors": [    {      "code": "NotAcceptable",      "title": "Not Acceptable"    }  ]}
423 Locked
// Status 423 Locked
{  "errors": [    {      "code": "AccountLocked",      "title": "Account is locked"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too Many Requests"    }  ]}
500 Internal Server Error
// Status 500 Internal Server Error
{  "errors": [    {      "code": "InternalServerError",      "title": "Internal Server Error"    }  ]}

Get My Unified Agent Statuses

  • GET /api/v2/agent_availabilities/agent_statuses/me

Returns the unified statuses available to the current agent. Unified agent statuses are returned in lexicographical order and are paginated. No other methods of sorting are supported.

With no query parameters, the initial page returned displays both default and custom unified statuses for the agent. To navigate to a different page of statuses, use the pagination links provided. The pagination links use the page[before] or page[after] parameters. The page[before] and page[after]parameters can't be used together in a single request.

Inferred status color

See Get Unified Agent Statuses for inferred status colors.

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
page[after]integerQueryfalseThe cursor returned in the next link in the preceding response
page[before]integerQueryfalseThe cursor returned in the prev link in the preceding response
page[size]integerQueryfalseThe maximum number of custom unified statuses returned per page. If not specified, defaults to 20

Code Samples

Curl
curl -v -u {email_address}/token:{api_token} \  'https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses/me?page%5Bafter%5D=203&page%5Bsize%5D=5' \  --header 'Zendesk-Api-Version: 2023-02-01' \  --header 'Content-Type: application/json'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/me?page[after]=1234&page[before]=1234&page[size]=88"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Zendesk-Api-Version", "2023-02-01")	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/me")		.newBuilder()		.addQueryParameter("page[after]", "1234")		.addQueryParameter("page[before]", "1234")		.addQueryParameter("page[size]", "88");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Zendesk-Api-Version", "2023-02-01")		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/me',  headers: {	'Zendesk-Api-Version': '2023-02-01',	'Content-Type': 'application/json',  },  params: {    'page[after]': '1234',    'page[before]': '1234',    'page[size]': '88',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/me?page[after]=1234&page[before]=1234&page[size]=88"headers = {	"Zendesk-Api-Version": "2023-02-01",	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/me")uri.query = URI.encode_www_form("page[after]": "1234", "page[before]": "1234", "page[size]": "88")request = Net::HTTP::Get.new(uri, "Zendesk-Api-Version": "2023-02-01", "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "custom": [    {      "attributes": {        "channels": {          "messaging": "away",          "support": "online",          "talk": "away"        },        "description": "Used while attending meetings",        "group_ids": [          123456,          234567        ],        "name": "In a meeting"      },      "id": 205,      "type": "agent_status",      "updated_at": "2021-07-21T17:32:28Z"    },    {      "attributes": {        "channels": {          "messaging": "away",          "support": "online",          "talk": "away"        },        "description": "Used while on a call",        "group_ids": [],        "name": "Custom Status 2"      },      "id": 206,      "type": "agent_status",      "updated_at": "2021-07-21T17:32:28Z"    }  ],  "default": [    {      "attributes": {        "description": "Can't receive work",        "name": "offline"      },      "id": 2,      "type": "agent_status"    },    {      "attributes": {        "description": "Can receive work",        "name": "online"      },      "id": 3,      "type": "agent_status"    }  ],  "links": {    "next": "https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses?page%5Bafter%5D=206",    "prev": "https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses?page%5Bbefore%5D=205"  },  "meta": {    "has_more": true  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "InvalidPaginationParameter",      "title": "page[size] must be a positive integer <= 100; got 0"    }  ]}
401 Unauthorized
// Status 401 Unauthorized
{  "errors": [    {      "code": "Unauthorized",      "title": "Unauthorized"    }  ]}
403 Forbidden
// Status 403 Forbidden
{  "errors": [    {      "code": "InvalidPermissions",      "title": "Forbidden"    }  ]}
406 Not Acceptable
// Status 406 Not Acceptable
{  "errors": [    {      "code": "NotAcceptable",      "title": "Not Acceptable"    }  ]}
423 Locked
// Status 423 Locked
{  "errors": [    {      "code": "AccountLocked",      "title": "Account is locked"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too Many Requests"    }  ]}
500 Internal Server Error
// Status 500 Internal Server Error
{  "errors": [    {      "code": "InternalServerError",      "title": "Internal Server Error"    }  ]}

Update the Agent's Unified Status

  • PUT /api/v2/agent_availabilities/agent_statuses/agents/{agent_id}

Update the agent's unified status. Requires omnichannel routing to be turned on for the account. The id in the request body corresponds to the unified status you wish to set the agent to.

The list of available unified statuses can be obtained via the following APIs:

  • For a list of an accounts unified statuses: GET /api/v2/agent_availabilities/agent_statuses.

  • For a list unified statuses available to a specific agent: GET /api/v2/agent_availabilities/agent_statuses/me.

Returns a Unified Agent Status object.

Group Permissions

Custom unified statuses may only be eligible for specific groups. The eligible group ids can be found as a custom unified status attribute. If an agent is ineligible to use the unified status in the request, it will be rejected with a 403 - NotEligibleForState response.

Group memberships for an agent can be found by querying the Groups API. This information can be cross-referenced with the group ids in the custom unified status attribute to help determine if an agent is eligible to use a given custom unified status.

Allowed For

  • Admins

Parameters

NameTypeInRequiredDescription
agent_idintegerPathtrueThe agent id

Example body

{  "id": "123"}

Code Samples

Curl
curl -v -u {email_address}/token:{api_token} \  --request PUT 'https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/1011' \  --header 'Zendesk-Api-Version: 2023-02-01' \  --header 'Content-Type: application/json' \  --data-raw '{ "id": 123 }'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/10011"	method := "PUT"	payload := strings.NewReader(`{  "id": "123"}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Zendesk-Api-Version", "2023-02-01")	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/10011")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"id\": \"123\"}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Zendesk-Api-Version", "2023-02-01")		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "id": "123"});
var config = {  method: 'PUT',  url: 'https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/10011',  headers: {	'Zendesk-Api-Version': '2023-02-01',	'Content-Type': 'application/json',  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/10011"
payload = json.loads("""{  "id": "123"}""")headers = {	"Zendesk-Api-Version": "2023-02-01",	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/10011")request = Net::HTTP::Put.new(uri, "Zendesk-Api-Version": "2023-02-01", "Content-Type": "application/json")request.body = %q({  "id": "123"})response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "data": {    "attributes": {      "agent_id": 10011,      "agent_status": {        "id": 123,        "name": "In a meeting"      }    },    "id": "agent_availabilities|10011",    "type": "agent_availabilities"  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "InvalidParameter",      "title": "Bad Request"    }  ]}
401 Unauthorized
// Status 401 Unauthorized
{  "errors": [    {      "code": "Unauthorized",      "title": "Authentication error"    }  ]}
403 Forbidden
// Status 403 Forbidden
{  "errors": [    {      "code": "InvalidPermissions",      "title": "Forbidden"    }  ]}
404 Not Found
// Status 404 Not Found
{  "errors": [    {      "code": "AgentNotFound",      "title": "Not Found"    }  ]}
406 Not Acceptable
// Status 406 Not Acceptable
{  "errors": [    {      "code": "NotAcceptable",      "title": "Not Acceptable"    }  ]}
409 Conflict
// Status 409 Conflict
{  "errors": [    {      "code": "ConflictUpdate",      "title": "The current agent status could not be updated because a previous update is still pending"    }  ]}
423 Locked
// Status 423 Locked
{  "errors": [    {      "code": "AccountLocked",      "title": "Account is locked"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too Many Requests"    }  ]}
500 Internal Server Error
// Status 500 Internal Server Error
{  "errors": [    {      "code": "InternalServerError",      "title": "Internal Server Error"    }  ]}

Update My Unified Status

  • PUT /api/v2/agent_availabilities/agent_statuses/agents/me

Update the current agent's unified status. Requires omnichannel routing to be turned on for the account. Use the GET /api/v2/agent_availabilities/agent_statuses/me endpoint to obtain a list of the available unified statuses for the current agent.

Returns a Unified Agent Status object.

Limitations

All limitations in Update the Agent's Unified Status apply here.

Allowed For

  • Agents

Example body

{  "id": "123"}

Code Samples

Curl
curl -v -u {email_address}/token:{api_token} \  --request PUT 'https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/me' \  --header 'Zendesk-Api-Version: 2023-02-01' \  --header 'Content-Type: application/json' \  --data-raw '{ "id": 123 }'
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/me"	method := "PUT"	payload := strings.NewReader(`{  "id": "123"}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Zendesk-Api-Version", "2023-02-01")	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/me")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"id\": \"123\"}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Zendesk-Api-Version", "2023-02-01")		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "id": "123"});
var config = {  method: 'PUT',  url: 'https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/me',  headers: {	'Zendesk-Api-Version': '2023-02-01',	'Content-Type': 'application/json',  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/me"
payload = json.loads("""{  "id": "123"}""")headers = {	"Zendesk-Api-Version": "2023-02-01",	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/me")request = Net::HTTP::Put.new(uri, "Zendesk-Api-Version": "2023-02-01", "Content-Type": "application/json")request.body = %q({  "id": "123"})response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "data": {    "attributes": {      "agent_id": 10011,      "agent_status": {        "id": 123,        "name": "In a meeting"      }    },    "id": "agent_availabilities|10011",    "type": "agent_availabilities"  }}
400 Bad Request
// Status 400 Bad Request
{  "errors": [    {      "code": "InvalidParameter",      "title": "Bad Request"    }  ]}
401 Unauthorized
// Status 401 Unauthorized
{  "errors": [    {      "code": "Unauthorized",      "title": "Authentication error"    }  ]}
403 Forbidden
// Status 403 Forbidden
{  "errors": [    {      "code": "InvalidPermissions",      "title": "Forbidden"    }  ]}
404 Not Found
// Status 404 Not Found
{  "errors": [    {      "code": "AgentNotFound",      "title": "Not Found"    }  ]}
406 Not Acceptable
// Status 406 Not Acceptable
{  "errors": [    {      "code": "NotAcceptable",      "title": "Not Acceptable"    }  ]}
409 Conflict
// Status 409 Conflict
{  "errors": [    {      "code": "ConflictUpdate",      "title": "The current agent status could not be updated because a previous update is still pending"    }  ]}
423 Locked
// Status 423 Locked
{  "errors": [    {      "code": "AccountLocked",      "title": "Account is locked"    }  ]}
429 Too Many Requests
// Status 429 Too Many Requests
{  "errors": [    {      "code": "TooManyRequests",      "title": "Too Many Requests"    }  ]}
500 Internal Server Error
// Status 500 Internal Server Error
{  "errors": [    {      "code": "InternalServerError",      "title": "Internal Server Error"    }  ]}