Zendesk Developers :: REST API Documentation

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 simple flat JSON objects which have the following keys.

Name	Type	Comment
id	integer	Automatically assigned when created
title	string	The title of the macro
active	boolean	Useful for determining if the macro should be displayed
restriction	object	Who may access this macro. Will be null when everyone in the account can access it.
actions	Actions	An object describing what the macro will do
created_at	date	The time the macro was created
updated_at	date	The time of the last update of the macro

Example

{
  "macro": {
    "id": 25,
    "title": "Tickets updated <12 Hours",
    "active": true,
    "actions": { ... },
    "restriction": {
      "type": "User",
      "id": 4
    }
  }
}

Actions

Actions consist of an array of one or more actions.

Example

{
 "actions": [
   {"field": "status", "value": "open"},
   {"field": "assignee_id", "value": "296220096"}
 ]
}

Each action in the array has the following properties:

Name	Type	Description
field	string	The name of a ticket field to modify
value	string	The new value of the field

Example action

{ "field": "status", "value": "solved" }

Actions reference

Triggers, automations, and macros share the following actions.

field	value
`status`	Sets the ticket status. Takes `new`, `open`, `pending`, `hold`, `solved`, or `closed`, except for macros, which don't take `new` or `closed`.
`type`	Sets the ticket type. Takes `question`, `incident`, `problem`, or `task`.
`priority`	Sets the ticket priority. Takes `low`, `normal`, `high`, or `urgent`. Macros also take `""` (set to no priority).
`group_id`	Assigns the ticket to a group. Takes `""` (unassign from a group if one has been assigned) or the numeric ID of a group.
`assignee_id`	Assigns the ticket to a person. Takes `""` (set to unassigned), `current_user`, or the numeric ID of an assignee or requester.
`set_tags`	A space-delimited list of tags to insert in the ticket. The action replaces the current tags.
`current_tags`	A space-delimited list of tags to add to existing tags.
`remove_tags`	A space-delimited list of tags to remove from existing tags.
`custom_fields_<id>`	Sets the value of a custom ticket field.

Additional actions for triggers and automations

In addition to the shared actions, triggers and automations share the following actions.

field	value
`satisfaction_score`	Sends a survey request to the ticket requester. Takes `offered` as a value.
`notification_user`	Sends an email to a user. Takes an array of three strings specifying the email recipient, subject, and body. See "Notification emails" below. Possible recipient value: `current_user`, `all_agent` (all non-restricted agents), `requester_id` (the current requester), `assignee_id` (the current assignee), or the numeric ID of an agent.
`notification_group`	Sends an email to a group. Takes an array of three strings specifying the email recipient, subject, and body. See "Notification emails" below. Possible recipient value: `group_id` (the currently assigned group), or the numeric ID of a group.
`notification_target`	Sends a message to an external target. Takes an array of two strings specifying the numeric ID of the target and the message body.
`tweet_requester`	Responds to the twitter requester with a tweet. Takes the text of the tweet.
`cc`	CC's somebody on the ticket. Takes `current_user` or the numeric ID of an agent.
`locale_id`	Sets the requester's language to one of your supported languages. Takes the numeric ID of a supported locale. See List locales to list the available locale IDs for the account.

Additional actions for macros

In addition to the shared actions, macros have the following actions.

field	value
`subject`	Replaces the subject of a ticket. Takes the subject text.
`comment_value`	Adds a comment to a ticket. Takes the comment text.
`comment_mode_is_public`	Makes a ticket comment public or private. Takes `true` (public) or `false` (private).

Notification emails

Notification emails are represented by an array of three strings specifying the email recipient, subject, and body.

Example

["293741756","Leaking radiator","Open the steam valve."]

The array is used for the value property of email notification actions. See "Additional actions for triggers and automations" above.

Example action

{
 "actions": [
   {"field":"notification_user","value":["293741756","Leaking radiator","Open the steam valve."]}
 ]
}

You can use dynamic content placeholders in the email subject and body. See Zendesk data object (placeholders) reference.

You can also use return (\r) and newline (\n) characters in the message body.

Example

["current_user","{{ticket.id}}: Leaking radiator","Open the steam valve.\r \nHope this helps."]

List Macros

GET /api/v2/macros.json

Lists all shared and personal macros available to the current user

Allowed For:

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/macros.json \
  -v -u {email}:{password}

Example Response

Status: 200 OK

{
  "macros": [
     {
      "id": 25,
      "title": "Close and Save",
      "active": true
      "actions": [ ... ],
      "restriction": { ... }
    },
    {
      "id": 26,
      "title": "Assign priority tag",
      "active": false
      "actions": [ ... ],
      "restriction": { ... }
    }
  ],
  "count": 2,
  "previous_page": null,
  "next_page": null
}

Getting Macros

GET /api/v2/macros/{id}.json

Allowed For:

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/macros/{id}.json \
  -v -u {email}:{password}

Example Response

Status: 200 OK

{
  "macro": {
    "id": 25,
    "title": "Tickets updated <12 Hours",
    "active": true
    "actions": [ ... ],
    "restriction": { ... }
  }
}

List active Macros

GET /api/v2/macros/active.json

Lists all active shared and personal macros available to the current user

Allowed For:

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/macros/active.json \
  -v -u {email}:{password}

Example Response

Status: 200 OK

{
  "macros": [
     {
      "id": 25,
      "title": "Close and Save",
      "active": true
      "actions": [ ... ],
      "restriction": { ... }
    },
    {
      "id": 28,
      "title": "Close and redirect to topics",
      "active": true
      "actions": [ ... ],
      "restriction": { ... }
    }
  ],
  "count": 2,
  "previous_page": null,
  "next_page": null
}

Create Macro

POST /api/v2/macros.json

Allowed For

Agents

Using curl

curl -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/macros.json \
  -H "Content-Type: application/json" -X POST -d @- <<JSON
    {"macro":
      {"title": "Roger Wilco II",
       "actions": [
         {"field": "status", "value": "solved"}
       ]
    }}
JSON

#### Example Response

```http
Status: 201 Created
Location: /api/v2/macros/{new-macro-id}.json

{
  "macro": {
    "id":   9873843,
    "title": "Roger Wilco",
    ...
  }
}

Update Macro

PUT /api/v2/macros/{id}.json

Allowed For

Agents

Using curl

curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/macros/{id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"macro": {"title": "Roger Wilco II"}}'

Example Response

Status: 200 OK

{
  "macro": {
    "id":   9873843,
    "title": "Roger Wilco II",
    ...
  }
}

Note

Updating an action updates the containing array, clearing the other actions. Include all your actions when updating any action.

Delete Macro

DELETE /api/v2/macros/{id}.json

Allowed For

Agents, restrictions apply on certain actions

Using curl

curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/macros/{id}.json \
  -X DELETE

Example Response

Status: 200 OK

Apply Macros

GET /api/v2/macros/{id}/apply.json

GET /api/v2/tickets/{ticket_id}/macros/{id}/apply.json

Applies a macro to a specific ticket, or to all applicable tickets.

Allowed For:

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/macros/{id}/apply.json \
  -u {email}:{password}

Example Response

{
  "result": {
    "ticket": {
      "id":               35436,
      "url":              "https://company.zendesk.com/api/v2/tickets/35436.json",
      "assignee_id":      235323,
      "group_id":         98738,
      "fields": [
        {
          "id":    27642,
          "value": "745"
        }
      ],
      ...
    },
    "comment": {
      "body": "Assigned to Agent Uno.",
      "public": false
    }
  }
}