Skip to main content
A macro is a reusable reply that agents insert from the inbox composer. This API creates and edits them, chooses the languages they are translated into, and reports how well each one performs as a suggested macro, so your tooling can manage the macro library without opening the dashboard.

Key Concepts

  • Macros — A title, a group (category, "general" for none), a body written as HTML with {{variable}} placeholders, and up to 3 tappable options. The API reaches org-wide macros only: a personal macro belongs to one agent and is never returned or changed here
  • Team-only macros — allowed_team_ids lists the teams whose agents see a macro in the inbox; empty means every agent. Agents who can edit macros in Settings → Macros always see every macro. Team IDs must belong to your organization, otherwise the request is rejected with a 400
  • Variables — Read-only. List macro variables returns the built-in and custom names you can use in a body. Custom variables and macro attachments are authored in Settings → Macros and cannot be written through the API. Attachments are returned on reads
  • Any language — Write a macro in whatever language you like; its language is detected automatically and returned as source_language
  • Translation languages — Choose up to 10 with Update macro settings. No languages are chosen by default, and then nothing is translated. Every macro is translated once into each chosen language, in the background, and editing a macro refreshes its translations. Choosing a new language translates every macro into it
  • Translations — Generated copies. Get macro translations shows the status and text per language, Retranslate a macro redoes them, and Set a macro translation replaces one language with your own wording. In the inbox, agents get the version in the customer’s language automatically. System variables are never translated; custom variables are translated with the macro
  • Suggested macros — exclude_from_suggestions keeps a macro out of the suggestions agents see. The workspace switch is read-only here (suggestions_enabled) and is changed in Settings → Workspace → Replies → Suggested macros
  • Suggestion insights — How each macro performs as a suggestion over the last 30 days, with a learned state of learning, steady, proven, muted, or off. See List macro suggestion insights
  • Scopes — macros:read for every GET, macros:write for everything that changes a macro, the translation languages, or a translation. Create an API key under Settings → API keys. See Authentication

Available Endpoints

List Macros

List every org-wide macro

Get Macro

Fetch one macro by id

Create Macro

Create an org-wide macro

Update Macro

Change any subset of a macro

Delete Macro

Permanently delete a macro

List Macro Variables

The variable names a macro body can use

Get Macro Settings

Read the translation languages and the suggestions switch

Update Macro Settings

Choose the languages macros are translated into

Get Macro Translations

Status and text of one macro’s translations

Retranslate Macro

Translate a macro again

Set Macro Translation

Use your own wording for one language

List Macro Suggestion Insights

How every macro performs as a suggestion

Get Macro Suggestion Insights

The same for one macro, with weekly counts