# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Zendesk Macros API
  version: 1.0.0
extends: openapi/zendesk-macros-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 19
- target: $.paths['/api/v2/macros/{macro_id}/attachments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the attachments on a macro
      effect: read
      questions:
      - Which files are attached to one of my Zendesk macros?
      - Can I see the attachments a specific macro sends with its reply?
      instructions:
      - text: Show me the files attached to this macro.
      - text: List every attachment linked to the macro I'm editing.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/{macro_id}/attachments'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload an attachment directly to a macro
      effect: write
      questions:
      - Can I upload a file and attach it to an existing macro in one step?
      - What's the limit on how many attachments one macro can carry?
      instructions:
      - text: Upload this file and attach it straight to the macro I'm working on.
      - text: Add a new attachment to an existing macro in a single upload.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/attachments'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a macro attachment to link later
      effect: write
      questions:
      - Can I upload a macro attachment now and link it to a macro later?
      - What happens to uploaded macro attachments that never get linked to a macro?
      instructions:
      - text: Upload this file as a standalone macro attachment I'll link to a macro afterwards.
      - text: Stage an unlinked macro attachment upload for a macro I haven't created yet.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/attachments/{attachment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a macro attachment
      effect: read
      questions:
      - What properties does a single macro attachment have, like its file name and size?
      - How can I look up one macro attachment by its id?
      instructions:
      - text: Show the details of this macro attachment.
      - text: Get the file name, size and URL of one specific macro attachment.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros'].get
  update:
    x-apievangelist-phrasing:
      intent: List all macros available to me
      effect: read
      questions:
      - How do I get every shared and personal macro in my Zendesk account?
      - Do admins see other agents' personal macros when listing macros?
      instructions:
      - text: List all the macros I have access to, active or not.
      - text: Pull the full macro list for the account, including personal macros.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a macro
      effect: write
      questions:
      - Can I create a new canned-response macro through the API?
      - What goes into a macro definition when I create one?
      instructions:
      - text: 'Create a new macro from this definition: {macro}.'
        slots:
          macro: requestBody.macro
      - text: Add a macro that sets status to pending and posts a reply.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/{macro_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single macro
      effect: read
      questions:
      - How can I see the actions and settings of one specific macro?
      - Where do I find a macro's title, actions and restrictions by id?
      instructions:
      - text: Show me the macro with this id and its actions.
      - text: Fetch the full definition of one macro.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/{macro_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a macro
      effect: write
      questions:
      - Can I change the actions or title of a macro I already created?
      - Is it possible to deactivate one existing macro via the API?
      instructions:
      - text: Update this existing macro with {macro}.
        slots:
          macro: requestBody.macro
      - text: Rename one of my macros and change what it does.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/{macro_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a macro
      effect: destructive
      questions:
      - Can I permanently remove a single macro I no longer use?
      - Are there restrictions on which agents can delete a macro?
      instructions:
      - text: Delete this one macro.
      - text: Remove the outdated macro from the account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/{macro_id}/apply'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview the field changes a macro makes
      effect: read
      questions:
      - What would a macro change on a ticket, without actually applying it?
      - Can I get just the ticket fields a macro would set?
      instructions:
      - text: Show me the changes this macro would make, without touching any ticket.
      - text: Preview only the field updates a macro produces.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/actions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the actions macros support
      effect: read
      questions:
      - Which actions are available to use inside Zendesk macros?
      - What kinds of things can a macro do to a ticket?
      instructions:
      - text: List the supported macro actions.
      - text: Show all the action types I can put in a macro.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/active'].get
  update:
    x-apievangelist-phrasing:
      intent: List active macros
      effect: read
      questions:
      - How do I see only the macros that are currently active?
      - Which of my shared and personal macros are switched on right now?
      instructions:
      - text: List only the active macros available to me.
      - text: Show the macros agents can currently apply, skipping inactive ones.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List macro categories
      effect: read
      questions:
      - What categories are my macros organized into?
      - Can I get the list of macro categories I have access to?
      instructions:
      - text: List all macro categories.
      - text: Show the categories used to group macros.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get definitions of macro actions
      effect: read
      questions:
      - What values can each macro action take, like the options for setting status?
      - Where do I find the title, type and allowed values of each macro action?
      instructions:
      - text: Get the definitions of every action a macro can perform.
      - text: Show the allowed values for each macro action type.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/destroy_many'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several macros at once
      effect: destructive
      questions:
      - Can I bulk delete a batch of macros in a single request?
      - Is there a way to remove many macros by id at the same time?
      instructions:
      - text: Delete the macros with ids {ids}.
        slots:
          ids: query.ids
      - text: 'Bulk remove these macros: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/new'].get
  update:
    x-apievangelist-phrasing:
      intent: Build an unsaved macro from a ticket
      effect: read
      questions:
      - Can I generate a macro draft based on an existing ticket?
      - How can I turn what's on a ticket into a macro replica without saving it?
      instructions:
      - text: Build an unsaved macro replica from ticket {ticket_id}.
        slots:
          ticket_id: query.ticket_id
      - text: Derive a draft macro from the fields on ticket {ticket_id}.
        slots:
          ticket_id: query.ticket_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search macros
      effect: read
      questions:
      - Can I search my macros by title to find the right one?
      - Is macro search paginated by offset only?
      instructions:
      - text: Search my macros for ones about refunds.
      - text: Find macros whose title matches a keyword.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/macros/update_many'].put
  update:
    x-apievangelist-phrasing:
      intent: Update several macros at once
      effect: write
      questions:
      - Can I change the position or active state of many macros in one call?
      - Is there a bulk update for macros?
      instructions:
      - text: Bulk update these macros with the changes I list.
      - text: Deactivate a batch of macros in a single request.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/tickets/{ticket_id}/macros/{macro_id}/apply'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a ticket after applying a macro
      effect: read
      questions:
      - What would the whole ticket look like after a macro is applied to it?
      - Can I preview a macro on a real ticket without changing it?
      instructions:
      - text: Show ticket {ticket_id} as it would look after applying this macro.
        slots:
          ticket_id: path.ticket_id
      - text: Preview the full ticket object for {ticket_id} with the macro applied, without saving.
        slots:
          ticket_id: path.ticket_id
      method: generated
      generated: '2026-09-26'