Macros API

The Macros API manages quick action templates that automate repetitive ticket operations. Macros can set status, priority, assignee, tags, and more with a single click.

Macro Object

{
  id: string;                    // UUID
  organization_id: string;       // UUID of the organization
  name: string;                  // Macro name
  description?: string;          // Description of what this macro does
  actions: MacroAction[];        // Array of actions to execute
  category?: string;             // Optional category for organization
  shortcut?: string;             // Keyboard shortcut (e.g., "ctrl+1")
  is_personal: boolean;          // Personal (user-only) or shared
  created_by: string;            // UUID of creator
  usage_count: number;           // Times this macro has been applied
  created_at: string;            // ISO timestamp
  updated_at: string;            // ISO timestamp
}

MacroAction Schema

{
  type: 'set_status' | 'set_priority' | 'assign_to' | 'add_tags' |
        'remove_tags' | 'send_email' | 'add_note' | 'set_group';
  value: any;  // Action-specific value
}

Action Types

List Macros

Retrieve all macros available to the user (personal and shared).

Procedure: macros.list

Authentication: Required

Input:

{
  category?: string;     // Filter by category
  includePersonal?: boolean;  // Include personal macros (default: true)
}

Example:

curl -X GET "https://your-domain.com/api/trpc/macros.list" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "uuid",
          "name": "Close as Resolved",
          "description": "Mark ticket as resolved and send thank you",
          "actions": [
            {"type": "set_status", "value": "resolved"},
            {"type": "add_tags", "value": ["resolved-by-agent"]}
          ],
          "category": "Resolution",
          "shortcut": "ctrl+r",
          "is_personal": false,
          "usage_count": 245,
          "created_at": "2024-01-01T00:00:00.000Z"
        },
        {
          "id": "uuid-2",
          "name": "Escalate to Engineering",
          "description": "Escalate technical issues to engineering team",
          "actions": [
            {"type": "set_priority", "value": "high"},
            {"type": "add_tags", "value": ["engineering", "escalated"]},
            {"type": "assign_to", "value": "eng-lead-uuid"}
          ],
          "category": "Escalation",
          "is_personal": false,
          "usage_count": 58,
          "created_at": "2024-01-05T00:00:00.000Z"
        }
      ]
    }
  }
}

Get Macro

Retrieve a single macro by ID.

Procedure: macros.get

Authentication: Required

Input:

{
  id: string;  // Macro UUID
}

Example:

curl -X GET "https://your-domain.com/api/trpc/macros.get?input=%7B%22id%22:%22macro-uuid%22%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "Close as Resolved",
        "description": "Mark ticket as resolved and send thank you",
        "actions": [
          {"type": "set_status", "value": "resolved"},
          {"type": "send_email", "value": {"subject": "Issue Resolved", "body": "Your issue has been resolved..."}}
        ],
        "category": "Resolution",
        "shortcut": "ctrl+r",
        "is_personal": false,
        "created_by": "user-uuid",
        "usage_count": 245,
        "created_at": "2024-01-01T00:00:00.000Z"
      }
    }
  }
}

Create Macro

Create a new macro.

Procedure: macros.create

Authentication: Required

Input:

{
  name: string;                  // 1-200 characters
  description?: string;          // Optional description
  actions: MacroAction[];        // Array of actions (required, min 1)
  category?: string;             // Optional category
  shortcut?: string;             // Optional keyboard shortcut
  isPersonal?: boolean;          // Personal macro (default: false)
}

Example:

curl -X POST "https://your-domain.com/api/trpc/macros.create" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "name": "Request More Info",
      "description": "Ask customer for additional details",
      "actions": [
        {"type": "set_status", "value": "pending"},
        {"type": "add_tags", "value": ["needs-info"]},
        {"type": "send_email", "value": {
          "subject": "Additional Information Needed",
          "body": "Thank you for contacting us. To help resolve your issue, could you please provide..."
        }}
      ],
      "category": "Information",
      "shortcut": "ctrl+i"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "Request More Info",
        "actions": [...],
        "category": "Information",
        "shortcut": "ctrl+i",
        "is_personal": false,
        "usage_count": 0,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
}

Update Macro

Update an existing macro.

Procedure: macros.update

Authentication: Required

Input:

{
  id: string;                    // Required, macro UUID
  name?: string;                 // 1-200 characters
  description?: string;
  actions?: MacroAction[];
  category?: string;
  shortcut?: string;
  isPersonal?: boolean;
}

Example:

curl -X POST "https://your-domain.com/api/trpc/macros.update" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "id": "macro-uuid",
      "actions": [
        {"type": "set_status", "value": "pending"},
        {"type": "add_tags", "value": ["needs-info", "waiting-customer"]}
      ]
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "Request More Info",
        "actions": [...],
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Notes:

• Users can only update their own personal macros
• Admins can update any shared macro

Delete Macro

Permanently delete a macro.

Procedure: macros.delete

Authentication: Required

Input:

{
  id: string;  // Macro UUID
}

Example:

curl -X POST "https://your-domain.com/api/trpc/macros.delete" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"id":"macro-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Notes:

• Users can only delete their own personal macros
• Admins can delete any shared macro

Apply Macro

Apply a macro to one or more tickets.

Procedure: macros.applyMacro

Authentication: Required

Input:

{
  macroId: string;       // Macro UUID to apply
  ticketIds: string[];   // Array of ticket UUIDs
}

Example:

curl -X POST "https://your-domain.com/api/trpc/macros.applyMacro" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "macroId": "macro-uuid",
      "ticketIds": ["ticket-uuid-1", "ticket-uuid-2"]
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "appliedCount": 2,
        "results": [
          {"ticketId": "ticket-uuid-1", "success": true},
          {"ticketId": "ticket-uuid-2", "success": true}
        ]
      }
    }
  }
}

Side Effects:

• Increments macro's usage_count
• Records application in history for AI training
• Stores ticket snapshot (before/after state) for training data
• Executes all macro actions on each ticket

Notes:

• Supports bulk application to multiple tickets
• Failed tickets don't stop processing of remaining tickets

Get Application History

Retrieve the history of macro applications.

Procedure: macros.getApplicationHistory

Authentication: Required

Input:

{
  macroId?: string;      // Filter by macro UUID
  ticketId?: string;     // Filter by ticket UUID
  userId?: string;       // Filter by user who applied
  limit?: number;        // 1-100, default: 50
  offset?: number;       // Pagination offset
}

Example:

curl -X GET "https://your-domain.com/api/trpc/macros.getApplicationHistory?input=%7B%22macroId%22:%22macro-uuid%22,%22limit%22:20%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "history": [
          {
            "id": "history-uuid",
            "macro_id": "macro-uuid",
            "ticket_id": "ticket-uuid",
            "user_id": "user-uuid",
            "ticket_snapshot_before": {
              "status": "open",
              "priority": "normal",
              "tags": []
            },
            "ticket_snapshot_after": {
              "status": "resolved",
              "priority": "normal",
              "tags": ["resolved-by-agent"]
            },
            "created_at": "2024-01-15T10:30:00.000Z",
            "macro": {
              "name": "Close as Resolved"
            },
            "user": {
              "name": "Alice Agent"
            }
          }
        ],
        "total": 245
      }
    }
  }
}

Notes:

• History is used for AI training to learn common workflows
• Snapshots capture ticket state before and after macro application

Get Application Stats

Retrieve usage statistics for macros.

Procedure: macros.getApplicationStats

Authentication: Required

Input:

{
  startDate?: string;    // ISO date filter
  endDate?: string;      // ISO date filter
  groupBy?: 'macro' | 'user' | 'day' | 'week';
}

Example:

curl -X GET "https://your-domain.com/api/trpc/macros.getApplicationStats?input=%7B%22groupBy%22:%22macro%22%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "stats": [
          {
            "macroId": "macro-uuid",
            "macroName": "Close as Resolved",
            "count": 245,
            "uniqueUsers": 5
          },
          {
            "macroId": "macro-uuid-2",
            "macroName": "Escalate to Engineering",
            "count": 58,
            "uniqueUsers": 3
          }
        ],
        "totals": {
          "totalApplications": 303,
          "uniqueMacros": 2,
          "uniqueUsers": 5
        }
      }
    }
  }
}

Action Value Formats

set_status

{"type": "set_status", "value": "pending"}

Valid values: open, pending, resolved, closed

set_priority

{"type": "set_priority", "value": "high"}

Valid values: low, normal, high, urgent

assign_to

{"type": "assign_to", "value": "user-uuid"}

Value must be a valid user UUID in the organization.

add_tags / remove_tags

{"type": "add_tags", "value": ["billing", "urgent"]}
{"type": "remove_tags", "value": ["new"]}

Value is an array of tag strings.

send_email

{
  "type": "send_email",
  "value": {
    "subject": "Re: Your Request",
    "body": "Thank you for contacting us..."
  }
}

Sends an email reply to the ticket requester.

add_note

{
  "type": "add_note",
  "value": {
    "content": "Escalated per customer request",
    "internal": true
  }
}

• internal: true - Only visible to agents
• internal: false - Visible to customer

set_group

{"type": "set_group", "value": "group-uuid"}

Value must be a valid group UUID in the organization.

Example Macros

Quick Resolution

{
  "name": "Resolved - No Action Needed",
  "actions": [
    {"type": "set_status", "value": "resolved"},
    {"type": "add_tags", "value": ["no-action-needed"]},
    {"type": "add_note", "value": {"content": "Closed without action required", "internal": true}}
  ]
}

Spam Handling

{
  "name": "Mark as Spam",
  "actions": [
    {"type": "set_status", "value": "closed"},
    {"type": "add_tags", "value": ["spam"]},
    {"type": "set_priority", "value": "low"}
  ]
}

Escalation

{
  "name": "Escalate to Manager",
  "actions": [
    {"type": "set_priority", "value": "urgent"},
    {"type": "add_tags", "value": ["escalated", "manager-review"]},
    {"type": "assign_to", "value": "manager-uuid"},
    {"type": "add_note", "value": {"content": "Escalated for manager review", "internal": true}}
  ]
}

Error Codes