Macros

Macros are reusable action templates that agents apply to tickets with a single click. They can set fields, add tags, and attach files.

The macro object

Attribute	Type	Description
id	string	Unique identifier
name	string	Macro name (max 128 characters)
description	string | null	Description (max 512 characters)
scope	string	personal or workspace
ownerId	string	Creator’s user ID
isActive	boolean	Whether the macro is active
rule	object	Action definition (see below)
createdAt	string	Creation time (ISO 8601 UTC)

Rule format

{
  "actions": [
    { "field": "status", "action": "set", "value": "pending" },
    { "field": "tags", "action": "add", "value": ["needs-info"] },
    { "field": "priority", "action": "set", "value": "high" }
  ]
}

Action types

Action	Description
set	Set the field to the specified value
add	Add values (used for array fields like tags)
remove	Remove values (used for array fields like tags)

List macros

GET /helpdesk/api/macros

Returns personal macros for the current user and all workspace macros.

Create a macro

POST /helpdesk/api/macros

Requires agent role or above.

Request body

{
  "name": "Close as resolved",
  "description": "Set status to resolved and add resolved tag",
  "scope": "workspace",
  "isActive": true,
  "rule": {
    "actions": [
      { "field": "status", "action": "set", "value": "resolved" },
      { "field": "tags", "action": "add", "value": ["resolved"] }
    ]
  }
}

Update a macro

PUT /helpdesk/api/macros/:macroId

Delete a macro

DELETE /helpdesk/api/macros/:macroId

Apply a macro

POST /helpdesk/api/macros/:macroId/apply

Applies the macro’s actions to a ticket.

Request body

{ "ticket_id": "tkt_abc123" }

Returns the updated ticket. Emits real-time WebSocket updates for the ticket.