Macros
A macro consists of one or more actions that modify the values of a ticket's fields. Macros are applied to tickets manually by agents. For example, you can create macros for support requests that agents can answer with a single, standard response. For more information, see Using macros to update and add comments to tickets.
JSON format
Macros are represented as JSON objects with the following properties:
| Name | Type | Read-only | Mandatory | Description |
|---|---|---|---|---|
| actions | array | false | true | Each action describes what the macro will do. See Actions reference |
| active | boolean | false | false | Useful for determining if the macro should be displayed |
| created_at | string | true | false | The time the macro was created |
| default | boolean | true | false | If true, the macro is a default macro |
| description | string | false | false | The description of the macro |
| id | integer | true | false | The id automatically assigned when a macro is created |
| position | integer | false | false | The position of the macro |
| raw_title | string | false | false | The raw format of the title of the macro |
| restriction | object | false | false | Access to this macro. A null value allows unrestricted access for all users in the account |
| title | string | false | true | The title of the macro |
| updated_at | string | true | false | The time of the last update of the macro |
| url | string | true | false | A URL to access the macro's details |
Example
{"actions": [{"field": "status","value": "solved"},{"field": "priority","value": "normal"},{"field": "type","value": "incident"},{"field": "assignee_id","value": "current_user"},{"field": "group_id","value": "current_groups"},{"field": "comment_value","value": "Thanks for your request. This issue you reported is a known issue. For more information, please visit our forums. "}],"active": true,"created_at": "2019-09-16T02:17:38Z","default": false,"description": null,"id": 360111062754,"position": 9999,"raw_title": "Close and redirect to topics","restriction": null,"title": "Close and redirect to topics","updated_at": "2019-09-16T02:17:38Z","url": "https://subdomain.zendesk.com/api/v2/macros/360111062754"}
List Macros
GET /api/v2/macros
Lists all shared and personal macros available to the current user. For admins, the API returns all macros for the account, including the personal macros of agents and other admins.
Pagination
- Cursor pagination (recommended)
- Offset pagination
See Pagination.
Returns a maximum of 100 records per page.
Allowed For
- Agents
Sideloads
The following sideloads are supported. The usage sideloads are only supported on the Support Professional or Suite Growth plan or above.
| Name | Will sideload |
|---|---|
| app_installation | The app installation that requires each macro, if present |
| categories | The macro categories |
| permissions | The permissions for each macro |
| usage_1h | The number of times each macro has been used in the past hour |
| usage_24h | The number of times each macro has been used in the past day |
| usage_7d | The number of times each macro has been used in the past week |
| usage_30d | The number of times each macro has been used in the past thirty days |
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| access | string | Query | false | Filter macros by access. Possible values are "personal", "agents", "shared", or "account". The "agents" value returns all personal macros for the account's agents and is only available to admins. |
| active | boolean | Query | false | Filter by active macros if true or inactive macros if false |
| category | integer | Query | false | Filter macros by category |
| group_id | integer | Query | false | Filter macros by group |
| include | string | Query | false | A sideload to include in the response. See Sideloads |
| only_viewable | boolean | Query | false | If true, returns only macros that can be applied to tickets. If false, returns all macros the current user can manage. Default is false |
| page | Query | false | Pagination parameter. Supports both traditional offset and cursor-based pagination: - Traditional: ?page=2 (integer page number) - Cursor: ?page[size]=50&page[after]=cursor (deepObject with size, after, before) These are mutually exclusive - use one format or the other, not both. | |
| per_page | integer | Query | false | Number of records to return per page. Note: Default and maximum values vary by endpoint. Check endpoint-specific documentation for limits. |
| sort_by | string | Query | false | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", "usage_7d", or "usage_30d". Defaults to alphabetical |
| sort_order | string | Query | false | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/macros \-H "Authorization: Bearer {access_token}"
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/macros?access=personal&active=true&category=25&group_id=25&include=usage_7d&only_viewable=false&page=&per_page=50&sort_by=alphabetical&sort_order=asc"method := "GET"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"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://example.zendesk.com/api/v2/macros").newBuilder().addQueryParameter("access", "personal").addQueryParameter("active", "true").addQueryParameter("category", "25").addQueryParameter("group_id", "25").addQueryParameter("include", "usage_7d").addQueryParameter("only_viewable", "false").addQueryParameter("page", "").addQueryParameter("per_page", "50").addQueryParameter("sort_by", "alphabetical").addQueryParameter("sort_order", "asc");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("GET", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'GET',url: 'https://example.zendesk.com/api/v2/macros',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},params: {'access': 'personal','active': 'true','category': '25','group_id': '25','include': 'usage_7d','only_viewable': 'false','page': '','per_page': '50','sort_by': 'alphabetical','sort_order': 'asc',},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/macros?access=personal&active=true&category=25&group_id=25&include=usage_7d&only_viewable=false&page=&per_page=50&sort_by=alphabetical&sort_order=asc"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("GET",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/macros")uri.query = URI.encode_www_form("access": "personal", "active": "true", "category": "25", "group_id": "25", "include": "usage_7d", "only_viewable": "false", "page": "", "per_page": "50", "sort_by": "alphabetical", "sort_order": "asc")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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{"count": 2,"macros": [{"actions": [],"active": true,"description": "Sets the ticket status to `solved`","id": 25,"position": 42,"restriction": {},"title": "Close and Save"},{"actions": [],"active": false,"description": "Adds a `priority` tag to the ticket","id": 26,"restriction": {},"title": "Assign priority tag"}],"next_page": null,"previous_page": null}
List Active Macros
GET /api/v2/macros/active
Lists all active shared and personal macros available to the current user.
Allowed For
- Agents
Sideloads
The following sideloads are supported. The usage sideloads are only supported on the Support Professional or Suite Growth plan or above.
| Name | Will sideload |
|---|---|
| app_installation | The app installation that requires each macro, if present |
| categories | The macro categories |
| permissions | The permissions for each macro |
| usage_1h | The number of times each macro has been used in the past hour |
| usage_24h | The number of times each macro has been used in the past day |
| usage_7d | The number of times each macro has been used in the past week |
| usage_30d | The number of times each macro has been used in the past thirty days |
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| access | string | Query | false | Filter macros by access. Possible values are "personal", "agents", "shared", or "account". The "agents" value returns all personal macros for the account's agents and is only available to admins. |
| category | integer | Query | false | Filter macros by category |
| group_id | integer | Query | false | Filter macros by group |
| include | string | Query | false | A sideload to include in the response. See Sideloads |
| sort_by | string | Query | false | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", "usage_7d", or "usage_30d". Defaults to alphabetical |
| sort_order | string | Query | false | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/macros/active \-H "Authorization: Bearer {access_token}"
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/macros/active?access=personal&category=25&group_id=25&include=usage_7d&sort_by=alphabetical&sort_order=asc"method := "GET"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"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://example.zendesk.com/api/v2/macros/active").newBuilder().addQueryParameter("access", "personal").addQueryParameter("category", "25").addQueryParameter("group_id", "25").addQueryParameter("include", "usage_7d").addQueryParameter("sort_by", "alphabetical").addQueryParameter("sort_order", "asc");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("GET", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'GET',url: 'https://example.zendesk.com/api/v2/macros/active',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},params: {'access': 'personal','category': '25','group_id': '25','include': 'usage_7d','sort_by': 'alphabetical','sort_order': 'asc',},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/macros/active?access=personal&category=25&group_id=25&include=usage_7d&sort_by=alphabetical&sort_order=asc"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("GET",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI