Unified statuses that are available for an account, this includes default unified statuses as well as custom unified statuses.

JSON format

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

Name Type Read-only Mandatory Description
custom array false false Array of Custom Unified Status objects
default array false false Array of Default Unified Status objects
links object false false Pagination links for the previous and next pages of data
meta object false false Other non-standard information about unified agent statuses response

Get Unified Agent Statuses

  • GET /api/v2/agent_availabilities/agent_statuses

Get 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 first page of default and custom unified statuses for the account is returned. 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.

Returns a Unified Agent Statuses object.

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 Zendesk's unified status switcher and around the user profile icon. The unified status switcher is only visible when Omnichannel Routing is enabled.

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

Name Type In Required Description
page[after] integer Query false The cursor returned in the next link in the preceding response
page[before] integer Query false The cursor returned in the prev link in the preceding response
page[size] integer Query false The maximum number of custom unified statuses returned per page, defaults to 20 if not specified

Code Samples

Curl
curl -v -u {email_address}:{password} \  '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",        "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",        "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 setting to be enabled for the account. The id in the request body corresponds to the unified status you wish to set the agent to. You can obtain the list the available unified states for the account via the GET /api/v2/agent_availabilities/agent_statuses API.

Returns a Unified Agent Status object.

Limitations

This API does not update the agent's chat status, which is employed by chat triggers and routing. As a result, the agent status set by the API is not used for routing chats. Consequently, chat triggers will not function properly when using "Account status" or "Department status" as a check condition for the "Messaging" and "Chat and messaging" channel options.

Allowed For

  • Admins

Parameters

Name Type In Required Description
agent_id integer Path true The agent id

Example body

{  "id": "123"}

Code Samples

Curl
curl -v -u {email_address}:{password} \  --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 state 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"    }  ]}