The Zendesk Macros API lets you programmatically manage the reusable, predefined actions that agents apply to Support tickets. With it, you can list, create, update, delete, and reorder macros; fetch details and available action definitions to build editors; and determine which macros are available for a given ticket and user.
openapi: 3.1.0
info:
version: "1.0"
title: Zendesk Macros
description: Needs a description.
paths:
/api/v2/macros:
get:
operationId: ListMacros
tags:
- Macros
summary: Zendesk Get Api V2 Macros
description: >
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](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
parameters:
- $ref: '#/components/parameters/MacroInclude'
- $ref: '#/components/parameters/MacroAccess'
- $ref: '#/components/parameters/MacroActive'
- $ref: '#/components/parameters/MacroCategory'
- $ref: '#/components/parameters/MacroGroupId'
- $ref: '#/components/parameters/MacroOnlyViewable'
- $ref: '#/components/parameters/MacroSortBy'
- $ref: '#/components/parameters/MacroSortOrder'
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacrosResponse'
examples:
default:
$ref: '#/components/examples/MacrosResponseExample'
post:
operationId: CreateMacro
tags:
- Macros
summary: Zendesk Post Api V2 Macros
description: |
#### Allowed For
* Agents
requestBody:
content:
application/json:
schema:
type: object
properties:
macro:
$ref: '#/components/schemas/MacroInput'
examples:
default:
value:
macro:
actions:
- field: status
value: solved
title: Roger Wilco
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
macro:
$ref: '#/components/schemas/MacroObject'
examples:
default:
$ref: '#/components/examples/CreateMacroResponseExample'
/api/v2/macros/{macro_id}:
parameters:
- $ref: '#/components/parameters/MacroId'
get:
operationId: ShowMacro
tags:
- Macros
summary: Zendesk Get Api V2 Macros Macro_id
description: |
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroResponse'
examples:
default:
$ref: '#/components/examples/MacroResponseExample'
put:
operationId: UpdateMacro
tags:
- Macros
summary: Zendesk Put Api V2 Macros Macro_id
description: |
#### Allowed For
* Agents
requestBody:
content:
application/json:
schema:
type: object
properties:
macro:
$ref: '#/components/schemas/MacroInput'
examples:
default:
value:
macro:
actions:
- field: status
value: solved
title: Sets the ticket status to `solved`
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
macro:
$ref: '#/components/schemas/MacroObject'
examples:
default:
$ref: '#/components/examples/UpdateMacroResponseExample'
delete:
operationId: DeleteMacro
tags:
- Macros
summary: Zendesk Delete Api V2 Macros Macro_id
description: |
#### Allowed For
* Agents, with restrictions applying on certain actions
responses:
'204':
description: No Content
/api/v2/macros/{macro_id}/apply:
parameters:
- $ref: '#/components/parameters/MacroId'
get:
operationId: ShowChangesToTicket
tags:
- Macros
summary: Zendesk Get Api V2 Macros Macro_id Apply
description: >
Returns the changes the macro would make to a ticket. It doesn't
actually
change a ticket. You can use the response data in a subsequent API call
to the [Tickets](/api-reference/ticketing/tickets/tickets/) endpoint to
update the ticket.
The response includes only the ticket fields that would be changed by
the
macro. To get the full ticket object after the macro is applied,
see [Show Ticket After Changes](#show-ticket-after-changes).
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroApplyTicketResponse'
examples:
default:
$ref: '#/components/examples/MacroChangesToTicketsResponseExample'
/api/v2/macros/{macro_id}/attachments:
parameters:
- $ref: '#/components/parameters/MacroId'
get:
operationId: ListMacroAttachments
tags:
- Macros
summary: Zendesk Get Api V2 Macros Macro_id Attachments
description: |
Lists the attachments associated with a macro.
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroAttachmentsResponse'
examples:
default:
$ref: '#/components/examples/MacroAttachmentsResponseExample'
post:
operationId: CreateAssociatedMacroAttachment
tags:
- Macros
summary: Zendesk Post Api V2 Macros Macro_id Attachments
description: >
Allows an attachment to be uploaded and associated with a macro at the
same time.
**Note:** A macro can be associated with up to five attachments.
#### Allowed For
* Agents
responses:
'201':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroAttachmentResponse'
examples:
default:
$ref: '#/components/examples/MacroAttachmentResponseExample'
/api/v2/macros/actions:
get:
operationId: ListMacrosActions
tags:
- Macros
summary: Zendesk Get Api V2 Macros Actions
description: |
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
actions:
type: array
items:
type: object
additionalProperties: true
examples:
default:
$ref: '#/components/examples/MacroActionsResponseExample'
/api/v2/macros/active:
get:
operationId: ListActiveMacros
tags:
- Macros
summary: Zendesk Get Api V2 Macros Active
description: >
Lists all active shared and personal macros available to the current
user.
#### Allowed For
* Agents
parameters:
- $ref: '#/components/parameters/MacroInclude'
- $ref: '#/components/parameters/MacroAccess'
- $ref: '#/components/parameters/MacroCategory'
- $ref: '#/components/parameters/MacroGroupId'
- $ref: '#/components/parameters/MacroSortBy'
- $ref: '#/components/parameters/MacroSortOrder'
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacrosResponse'
examples:
default:
$ref: '#/components/examples/MacrosResponseExample'
/api/v2/macros/attachments:
post:
operationId: CreateMacroAttachment
tags:
- Macros
summary: Zendesk Post Api V2 Macros Attachments
description: >
Allows an attachment to be uploaded that can be associated with a macro
at a later time.
**Note:** To ensure an uploaded attachment is not lost, associate it
with a macro as soon as possible. From time to time, old attachments
that are not not associated with any macro are purged.
#### Allowed For
* Agents
responses:
'201':
description: Created Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroAttachmentResponse'
examples:
default:
$ref: '#/components/examples/MacroAttachmentResponseExample'
/api/v2/macros/attachments/{attachment_id}:
parameters:
- $ref: '#/components/parameters/AttachmentId'
get:
operationId: ShowMacroAttachment
tags:
- Macros
summary: Zendesk Get Api V2 Macros Attachments Attachment_id
description: |
Shows the properties of the specified macro attachment.
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroAttachmentResponse'
examples:
default:
$ref: '#/components/examples/MacroAttachmentResponseExample'
/api/v2/macros/categories:
get:
operationId: ListMacroCategories
tags:
- Macros
summary: Zendesk Get Api V2 Macros Categories
description: |
Lists all macro categories available to the current user.
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroCategoriesResponse'
examples:
default:
$ref: '#/components/examples/MacroCategoriesResponseExample'
/api/v2/macros/definitions:
get:
operationId: ListMacroActionDefinitions
tags:
- Macros
summary: Zendesk Get Api V2 Macros Definitions
description: >
Returns the definitions of the actions a macro can perform. For example,
one action can set the status of a ticket. The definition of the action
includes a title ("Status"), a type ("list"), and possible values. For a
list of support actions, see [Actions
reference](/documentation/ticketing/reference-guides/actions-reference).
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
definitions:
type: object
properties:
actions:
type: array
items:
type: object
additionalProperties: true
examples:
default:
$ref: '#/components/examples/ShowDerivedMacroResponseExample'
/api/v2/macros/destroy_many:
delete:
operationId: DeleteManyMacros
tags:
- Macros
summary: Zendesk Delete Api V2 Macros Destroy_many
description: >
Deletes the macros corresponding to the provided comma-separated list of
IDs.
#### Allowed For
* Agents
parameters:
- name: ids
in: query
description: The IDs of the macros to delete
required: true
schema:
type: array
items:
type: integer
example:
- 1
- 2
- 3
responses:
'204':
description: No Content
/api/v2/macros/new:
parameters:
- $ref: '#/components/parameters/MacroIdQuery'
- name: ticket_id
in: query
description: The ID of the ticket from which to build a macro replica
required: true
schema:
type: integer
example: 35436
get:
operationId: ShowDerivedMacro
tags:
- Macros
summary: Zendesk Get Api V2 Macros New
description: >
Returns an unpersisted macro representation derived from a ticket or
macro.
The endpoint takes one of the following query parameters: `macro_id` or
`ticket_id`. If you include both, `macro_id` is used.
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroResponse'
examples:
default:
$ref: '#/components/examples/MacroResponseExample'
/api/v2/macros/search:
parameters:
- $ref: '#/components/parameters/MacroInclude'
- $ref: '#/components/parameters/MacroAccess'
- $ref: '#/components/parameters/MacroActive'
- $ref: '#/components/parameters/MacroCategory'
- $ref: '#/components/parameters/MacroGroupId'
- $ref: '#/components/parameters/MacroOnlyViewable'
- $ref: '#/components/parameters/MacroSearchSortBy'
- $ref: '#/components/parameters/MacroSortOrder'
- $ref: '#/components/parameters/MacroQuery'
get:
operationId: SearchMacro
tags:
- Macros
summary: Zendesk Get Api V2 Macros Search
description: >
#### Pagination
* Offset pagination only
See [Using Offset
Pagination](/api-reference/introduction/pagination/#using-offset-pagination).
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacrosResponse'
examples:
default:
$ref: '#/components/examples/MacrosResponseExample'
/api/v2/macros/update_many:
put:
operationId: UpdateManyMacros
tags:
- Macros
summary: Zendesk Put Api V2 Macros Update_many
description: |
Updates the provided macros with the specified changes.
#### Allowed For
* Agents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MacroUpdateManyInput'
examples:
default:
value:
macros:
- active: false
id: 25
- id: 23
position: 5
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacrosResponse'
examples:
default:
$ref: '#/components/examples/MacrosResponseExample'
/api/v2/tickets/{ticket_id}/macros/{macro_id}/apply:
parameters:
- $ref: '#/components/parameters/MacroId'
- name: ticket_id
in: path
description: The ID of the ticket
required: true
schema:
type: integer
example: 35436
get:
operationId: ShowTicketAfterChanges
tags:
- Macros
summary: Zendesk Get Api V2 Tickets Ticket_id Macros Macro_id Apply
description: >
Returns the full ticket object as it would be after applying the macro
to the ticket.
It doesn't actually change the ticket.
To get only the ticket fields that would be changed by the macro,
see [Show Changes to Ticket](#show-changes-to-ticket).
#### Allowed For
* Agents
responses:
'200':
description: Success Response
content:
application/json:
schema:
$ref: '#/components/schemas/MacroApplyTicketResponse'
examples:
default:
$ref: '#/components/examples/MacroChangesToTicketsResponseExample'
components:
schemas:
MacrosResponse:
type: object
allOf:
- type: object
properties:
macros:
type: array
items:
$ref: '#/components/schemas/MacroObject'
- $ref: '#/components/schemas/OffsetPaginationObject'
MacroResponse:
type: object
properties:
macro:
$ref: '#/components/schemas/MacroObject'
MacroApplyTicketResponse:
type: object
properties:
result:
type: object
properties:
ticket:
type: object
properties:
assignee_id:
type: integer
comment:
type: object
properties:
body:
type: string
public:
type: boolean
scoped_body:
type: array
items:
type: array
items:
type: string
fields:
type: object
properties:
id:
type: integer
value:
type: string
group_id:
type: integer
id:
type: integer
url:
type: string
MacroAttachmentsResponse:
type: object
properties:
macro_attachments:
type: array
items:
$ref: '#/components/schemas/MacroAttachmentObject'
MacroAttachmentResponse:
type: object
properties:
macro_attachment:
$ref: '#/components/schemas/MacroAttachmentObject'
MacroCategoriesResponse:
type: object
properties:
categories:
type: array
items:
type: string
tags:
- name: Macros