Unified Agent Statuses

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:

Name	Type	Read-only	Mandatory	Description
custom	array	true	false	Array of Custom Unified Status objects
default	array	true	false	Array of Default Unified Status objects
links	object	true	false	Pagination links for the previous and next pages of data
meta	object	true	false	Other 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 display color of the unified 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 following considerations:

Agent’s product access: The inferred status in the status switcher considers only channels the agent has access to. For example, an agent with only Support and Talk access will not have the Messaging channel status considered when displaying the inferred status in the status dropdown.

Channel to status mapping: The inferred status is evaluated in the following order of priority:

• Priority 1: If one or more channels are online, the inferred status is online. For example, [online, away, offline] is inferred as online, and [online, offline] is inferred as online
• Priority 2: If both away and transfers_only channels are present, the inferred status is determined by the status that occurs the most. If there is an equal number of away and transfers_only channels, precedence is given to transfers_only for the inferred status. For example, [away, transfers_only, offline] is inferred as transfers_only, [away, away, transfers_only] is inferred as away
• Priority 3: If either away or transfers_only is present, and not both, then the inferred status follows that status. The presence of offline channels does not affect the inferred status. For example, [away, away, offline] is inferred as away, [away, offline] is inferred as away
• Priority 4: If all channels are offline, then the inferred status is offline, this applies to all statuses.

This ensures that the inferred status color is accurately reflected based on the channels each agent has access to in relation to the channel to status mapping of the unified status.

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. 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

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. 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

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}/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 requests
import 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"
    }
  ]
}

Bulk Update the Unified Status of Many Agents

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

Accepts a comma-separated list of up to 100 agents. The id in the request body corresponds to the unified status you wish to set the agent to. For the standard values, see the API introduction. Returns a Job Status object and queues a background job to do the work. Use the Job Status endpoint to check for the job's completion.

Limitations

All limitations in Update the Agent's Unified Status apply to every agent being updated.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
ids	string	Path	true	Comma-separated list of agent ids

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/update_many?ids=10011,10012' \
  --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/update_many"
	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/update_many")
		.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/update_many',
  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 requests
import json

url = "https://support.zendesk.com/api/v2/agent_availabilities/agent_statuses/agents/update_many"

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/update_many")
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

{
  "job_status": {
    "id": "01JB1GQENJMK3X983SCQC0GAKE",
    "message": "Job is queued",
    "progress": 0,
    "results": [],
    "status": "queued",
    "total": 2,
    "url": "https://example.zendesk.com/api/v2/agent_availabilities/agent_statuses/job_statuses/01JB1GQENJMK3X983SCQC0GAKE"
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "InvalidParameter",
      "title": "Bad Request"
    },
    {
      "code": "InvalidParameter",
      "title": "Number of bulk job items should not exceed 100"
    },
    {
      "code": "InvalidParameter",
      "title": "Invalid agent ids"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "Unauthorized",
      "title": "Authentication error"
    }
  ]
}

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 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 requests
import 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"
    }
  ]
}