> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Macros

> The Macros API lets you manage saved-reply macros, choose the languages they are translated into, and read how suggested macros are doing.

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 category, 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
* **Variables** — Read-only. [List macro variables](./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](./update-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** — Read-only generated copies. [Get macro translations](./translations) shows the status and text per language, and [Retranslate a macro](./retranslate) redoes them. In the inbox, agents get the version in the customer's language automatically. Variables are never translated
* **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 → 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](./suggestion-insights-list)
* **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](/api-reference/authentication)

## Available Endpoints

<CardGroup>
  <Card title="List Macros" icon="list" href="./list">
    List every org-wide macro
  </Card>

  <Card title="Get Macro" icon="eye" href="./get">
    Fetch one macro by id
  </Card>

  <Card title="Create Macro" icon="plus" href="./create">
    Create an org-wide macro
  </Card>

  <Card title="Update Macro" icon="pen" href="./update">
    Change any subset of a macro
  </Card>

  <Card title="Delete Macro" icon="trash" href="./delete">
    Permanently delete a macro
  </Card>

  <Card title="List Macro Variables" icon="code" href="./variables">
    The variable names a macro body can use
  </Card>

  <Card title="Get Macro Settings" icon="gear" href="./get-settings">
    Read the translation languages and the suggestions switch
  </Card>

  <Card title="Update Macro Settings" icon="language" href="./update-settings">
    Choose the languages macros are translated into
  </Card>

  <Card title="Get Macro Translations" icon="globe" href="./translations">
    Status and text of one macro's translations
  </Card>

  <Card title="Retranslate Macro" icon="rotate" href="./retranslate">
    Translate a macro again
  </Card>

  <Card title="List Macro Suggestion Insights" icon="chart-line" href="./suggestion-insights-list">
    How every macro performs as a suggestion
  </Card>

  <Card title="Get Macro Suggestion Insights" icon="chart-simple" href="./suggestion-insights-get">
    The same for one macro, with weekly counts
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.