Skip to main content

Create Support Macro

POST 
/api/support/admin/macros

Creates a macro: a canned reply with placeholders, an optional /shortcut, and optional ticket actions applied when an agent uses it. The caller is recorded as the author; macros default to shared.

Required scope: support:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Request body

  • name (string, required, max 100) — the macro's display name. Whitespace is trimmed.
  • shortcut (string, optional, nullable, max 40) — a short handle agents type to pick the macro, e.g. thanks. Letters, digits, dashes and underscores only; stored lower-cased; must be unique across macros (a taken shortcut fails with a 422). Null removes it.
  • body_text (string, required, max 20000) — the plain-text reply body. May contain placeholders (below).
  • body_html (string, optional, nullable, max 60000) — the HTML reply body. When omitted or blank it is generated from body_text.
  • actions (object, optional, nullable) — ticket changes to apply when an agent uses the macro. Empty values are dropped; when nothing remains the macro has no actions (null).
  • actions.status (string, optional, nullable) — one of: open, in_progress, waiting_on_customer, awaiting_release, resolved, closed.
  • actions.priority (string, optional, nullable) — one of: low, medium, high, urgent.
  • actions.type (string, optional, nullable) — one of: bug, question, feature_request, billing.
  • actions.group_key (string, optional, nullable) — the key of an existing support group (e.g. customer_support, billing, escalations).
  • actions.add_tags (string[], optional, nullable, max 10) — tags to add to the ticket. Entries are trimmed and de-duplicated.
  • actions.add_tags[] (string, max 40) — each tag.
  • is_shared (boolean, optional) — true makes the macro visible to every agent; false keeps it private to its author. Default: true.

Placeholders: write {{key}} anywhere in body_text or body_html (whitespace inside the braces is allowed; keys are case-insensitive). When an agent renders the macro against a ticket each placeholder is replaced — HTML-escaped in body_html, raw in body_text. An unknown key renders as an empty string. Supported keys:

  • {{ticket.id}} — the ticket id, e.g. 2451
  • {{ticket.number}} — the ticket reference, e.g. #2451
  • {{ticket.subject}} — the ticket subject
  • {{ticket.status}} — the current status label
  • {{ticket.priority}} — the current priority label
  • {{requester.name}} — the requester's full name
  • {{requester.first_name}} — the requester's first name
  • {{requester.email}} — the requester's email address
  • {{agent.name}} — the rendering agent's display name
  • {{agent.first_name}} — the rendering agent's first name
  • {{agent.signature}} — the rendering agent's signature
  • {{tenant.id}} — the tenant id
  • {{tenant.name}} — the tenant name

Response fields: id (integer), name (string), shortcut (string, nullable), body_html (string), body_text (string), actions (object, nullable — status, priority, type, group_key, add_tags[]), is_shared (boolean), created_by (object, nullable — id, name), is_mine (boolean — whether the caller authored the macro), created_at / updated_at (ISO-8601).

Authentication: Bearer token with the support:write scope, or an authenticated session, from a caller with an active support role who also holds the support admin role. No tenant context — this endpoint is central.

Request​

Responses​

Created

Response Headers
    Content-Type