> ## 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 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](https://docs.open.cx/api-reference/macros/variables.md) 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](https://docs.open.cx/api-reference/macros/update-settings.md). 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](https://docs.open.cx/api-reference/macros/translations.md) shows the status and text per language, [Retranslate a macro](https://docs.open.cx/api-reference/macros/retranslate.md) redoes them, and [Set a macro translation](https://docs.open.cx/api-reference/macros/set-translation.md) 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](https://docs.open.cx/api-reference/macros/suggestion-insights-list.md)
* **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](https://docs.open.cx/api-reference/authentication.md)

## Available Endpoints

> [card] [List Macros](https://docs.open.cx/api-reference/macros/list.md)
>
> List every org-wide macro

> [card] [Get Macro](https://docs.open.cx/api-reference/macros/get.md)
>
> Fetch one macro by id

> [card] [Create Macro](https://docs.open.cx/api-reference/macros/create.md)
>
> Create an org-wide macro

> [card] [Update Macro](https://docs.open.cx/api-reference/macros/update.md)
>
> Change any subset of a macro

> [card] [Delete Macro](https://docs.open.cx/api-reference/macros/delete.md)
>
> Permanently delete a macro

> [card] [List Macro Variables](https://docs.open.cx/api-reference/macros/variables.md)
>
> The variable names a macro body can use

> [card] [Get Macro Settings](https://docs.open.cx/api-reference/macros/get-settings.md)
>
> Read the translation languages and the suggestions switch

> [card] [Update Macro Settings](https://docs.open.cx/api-reference/macros/update-settings.md)
>
> Choose the languages macros are translated into

> [card] [Get Macro Translations](https://docs.open.cx/api-reference/macros/translations.md)
>
> Status and text of one macro's translations

> [card] [Retranslate Macro](https://docs.open.cx/api-reference/macros/retranslate.md)
>
> Translate a macro again

> [card] [Set Macro Translation](https://docs.open.cx/api-reference/macros/set-translation.md)
>
> Use your own wording for one language

> [card] [List Macro Suggestion Insights](https://docs.open.cx/api-reference/macros/suggestion-insights-list.md)
>
> How every macro performs as a suggestion

> [card] [Get Macro Suggestion Insights](https://docs.open.cx/api-reference/macros/suggestion-insights-get.md)
>
> The same for one macro, with weekly counts


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