> ## 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 and variables setup

> Create and organize macros, limit them to teams, define reusable variables, and translate macros into your customers' languages from Settings → Macros.

Macros are saved replies your agents insert from the inbox composer. Each one can carry variables that fill in the customer's details, attachments, tappable options, linked workflows and translations into your customers' languages. Use **Settings → Macros** to build and maintain the library.

> [!NOTE]
>
> **Settings → Macros** in your [OpenCX dashboard](https://platform.open.cx/settings/saved-replies). Creating or changing org-wide macros, variables and translation languages requires the **Macros settings** permission with **Write** in [Roles](https://docs.open.cx/security/roles.md). With **Read** only, you can still create and edit your own personal macros. For how agents insert macros, see [Composer toolbar](https://docs.open.cx/inbox/intro.md#composer-toolbar) and [Translated macros](https://docs.open.cx/inbox/intro.md#translated-macros).

The page has three sections:

| Section | What it holds |
| - | - |
| **Translate macros** | The languages every macro is translated into |
| **Variables** | Your reusable text snippets |
| **Macros** | The macros themselves, with search, groups and per-macro actions |

## Create a macro

![Creating the macro Order running late in the Delivery group with the contact.first\_name variable](https://mintcdn.com/openchat/hiyaCL2S28Hya6Q7/images/ticketing/macro-create.gif?s=b0178bcf3f7f4618c6f20e4ba513466a)

Add a macro to the Delivery group with the customer's first name as a variable, and it appears under Delivery.

**1. Open the dialog**

Select **New macro** in the **Macros** section. To create one inside a group, select **+** on that group instead.

**2. Name it and place it**

Enter a title. Under it, choose a **Group**, the **Teams** that see the macro, and who it is **Visible to**: **Everyone in the organization** or **Only me**. Visibility can't be changed after the macro is created.

**3. Write the content**

Type the reply under **Content**. Type `{{` to insert a variable such as `{{contact.first_name}}`. Formatting is limited to what every channel can carry: bold, italic, strikethrough, links, lists and inline images.

**4. Add the extras you need**

Use **Attach files**, **Add option**, **Add workflow** and **Suggest this macro** as described below, then select **Create**.

| Property | What it does | Limits |
| - | - | - |
| **Group** | Files the macro under a group. **General** means no group. | Pick an existing group or type a new name and select **Create** |
| **Teams** | Shows an org-wide macro only to agents in those teams. Empty means every agent. | Org-wide macros only; hidden when your workspace has no teams |
| **Attachments** | Files sent with the macro. Each sent message gets its own copy. | Up to 10 files, 25 MB each |
| **Options** | Buttons the customer can tap. Each is **Send as reply** or **Trigger workflow**. | Org-wide macros only; up to 3, 20 characters each |
| **Workflows** | Workflows that run when an agent sends the macro | Org-wide macros only |
| **Suggest this macro** | Lets the macro appear as a suggested macro | Shown only while suggestions are on for the workspace |

Search covers each macro's title and body. Once you have two or more groups, each group becomes a section you can open and close; select **New group**, name it and pick the macros that move into it. See [Macro groups and team-only macros](https://docs.open.cx/inbox/intro.md#macro-groups-and-team-only-macros).

## Control who sees a macro

* **Everyone in the organization** makes the macro available to every agent, or to the chosen **Teams**. People with **Macros settings** Write always see every team-limited macro so they can manage them.
* **Only me** keeps the macro to you. Agents without **Macros settings** Write can only create these.
* **Make my own version** on an org-wide macro's row creates a personal copy that replaces the original everywhere you use macros. Your teammates keep the original. You can have one personal version of each org-wide macro, and it sends the original's options.

## Reuse text with variables

A variable is a `{{name}}` placeholder that is filled in when an agent inserts the macro. There are two kinds.

**System variables** come from the session. They always contain a dot.

| Variable | Filled with |
| - | - |
| `{{agent.full_name}}`, `{{agent.first_name}}`, `{{agent.email}}` | The replying agent. Names use the name customers see for that agent. |
| `{{contact.full_name}}`, `{{contact.first_name}}`, `{{contact.last_name}}`, `{{contact.email}}`, `{{contact.phone}}` | The session's contact. First and last name are the first and last word of the contact's name. |
| `{{session.number}}`, `{{session.status}}`, `{{session.language}}` | The current session |
| `{{org.name}}` | Your organization's name |

**Custom variables** are snippets you write once and reuse, such as a refund policy. Create one with **New variable** in the **Variables** section. A name uses letters, digits, underscores or dashes, with no dots or spaces, up to 64 characters, and must be unique. Reference it as `{{refund_policy}}`. A custom variable can itself contain system or custom variables; they are filled in too.

How variables behave:

* A reference that matches nothing, such as a typo, is left empty in the sent message. It never shows as raw `{{...}}` text.
* Renaming a custom variable does not update the macros that use the old name. Update those macros, or they insert nothing in that spot.
* A custom variable can't reference itself, directly or through other variables.
* You can't delete a custom variable while a macro or another variable uses it. The error names them.

Variables are created only in the dashboard. Integrations can read the list through [List macro variables](https://docs.open.cx/api-reference/macros/variables.md) but can't change it.

## Translate macros automatically

Write each macro in any language; OpenCX detects it. In **Translate macros**, select **Add language** and pick up to 10 languages. Every macro, including personal ones, is translated into each language in the background, and a line under the chips shows how many are still in progress. No languages are chosen by default, so macros are sent as written.

What gets translated:

* The title, the body and option labels. Attachments are not translated.
* System variables are never translated; they are filled in when the agent inserts the macro. The text of custom variables is translated with the macro.
* Terms in your [translation glossary](https://docs.open.cx/ticketing/real-time-translation.md#keep-terms-consistent-with-the-glossary) are kept exactly as written.

When an agent inserts a macro, they get the version in the session's language. The macro is inserted as written when it is already in that language, when that language is not one you chose, or while its translation is still being prepared. See [Translated macros](https://docs.open.cx/inbox/intro.md#translated-macros) for the agent view.

### Check or replace a translation

Open a saved macro. Beside **Content**, a language button shows **Original**; pick a language to preview its translation. A failed language shows **Couldn't translate to** that language with **Try again**. **Retranslate** (the refresh icon) translates the macro again into every language. A macro with no translations yet shows **Translate now**.

To use your own wording for one language, preview it and select **Edit**, change the title or body, then **Save**. An **Overridden** tag shows who wrote it, and each change is recorded in the [audit log](https://docs.open.cx/security/audit-logs.md).

### What happens when the macro changes

| You change | Effect on its translations |
| - | - |
| The macro's title, body or options | Every language, including your own wording, is translated again from the new text. Agents insert the original until the new translations are ready. |
| A custom variable the macro uses | Same as above |
| The group, teams, attachments or the **Suggest this macro** switch | Nothing. Translations and your own wording stay. |
| **Retranslate** | Every language, including your own wording, is replaced by a new automatic translation |
| Remove a language | It stops being used. Its translations are kept, so adding the language back brings them back. |

> [!WARNING]
>
> Your own wording lasts only until the macro's text changes. After an edit, re-check the languages you overrode and apply your wording again.

## Run a workflow from a macro

Two ways to trigger automation from an org-wide macro:

* **Workflows**: select **Add workflow** and pick a workflow with the **Macro Called** trigger. It runs every time an agent sends the macro. Each workflow can be linked to one macro; one already in use shows **Used by** and that macro's name. Removing a workflow from a macro turns the workflow off. Linking requires **Workflows** Write as well as **Macros settings** Write.
* **Options** set to **Trigger workflow**: a customer's tap runs your **Macro Option Clicked** workflows instead of reaching the AI agent.

Details and channel support are in [Macro workflows](https://docs.open.cx/inbox/intro.md#macro-workflows) and [Macro options](https://docs.open.cx/inbox/intro.md#macro-options).

## Review history and suggestion insights

* **Version history** on a macro's row opens every saved version of a macro with what changed. History is read-only. It is available to people with **Macros settings** Write, and to the owner of a personal macro. See [Macro version history](https://docs.open.cx/inbox/intro.md#macro-version-history).
* While suggested macros are on for the workspace, a sparkle count on a macro's row shows how often it was used when suggested in the last 30 days, and **Not suggested** marks macros with **Suggest this macro** off.
* In a saved macro's dialog, **Insights** shows how suggestions for it are doing:

| Mark | Meaning |
| - | - |
| **Learning** | Suggested fewer than 10 times in the last 30 days |
| **Steady** | Suggested at the usual bar |
| **Proven** | Agents use it when suggested, or look for it themselves, so it is suggested a little earlier |
| **Muted** | Suggested 10 or more times in 30 days and never used, so it needs a closer match before it appears again |

Turn suggestions on or off for everyone in [Workspace settings](https://docs.open.cx/ticketing/workspace-settings.md#replies). Each agent opts in under [Personalization](https://docs.open.cx/ticketing/personalization.md). See [Suggested macros](https://docs.open.cx/inbox/intro.md#suggested-macros) for what agents see.

## Manage macros through the API

The [Macros API](https://docs.open.cx/api-reference/macros/index.md) covers org-wide macros: [list](https://docs.open.cx/api-reference/macros/list.md), [create](https://docs.open.cx/api-reference/macros/create.md), [update](https://docs.open.cx/api-reference/macros/update.md) and [delete](https://docs.open.cx/api-reference/macros/delete.md) them, [read or change the translation languages](https://docs.open.cx/api-reference/macros/get-settings.md), [read translations](https://docs.open.cx/api-reference/macros/translations.md), [retranslate](https://docs.open.cx/api-reference/macros/retranslate.md), [set your own wording](https://docs.open.cx/api-reference/macros/set-translation.md), and [read suggestion insights](https://docs.open.cx/api-reference/macros/suggestion-insights-list.md). Personal macros, variables and attachments can't be written through the API.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| Part of a sent macro is blank | It references a variable that doesn't exist, often after a rename | Fix the reference in the macro, or rename the variable back |
| Saving a variable fails with a circular reference | The variable uses itself through another variable | Remove one of the references in the chain the error lists |
| **Add language**, **New variable** or **Edit macro** is disabled | Your role lacks **Macros settings** Write | Ask an admin to grant it in [Roles](https://docs.open.cx/security/roles.md) |
| A macro row shows a language as failed | That translation couldn't be produced | Open the macro, pick the language and select **Try again**, or **Edit** it yourself |

***

## Related Documentation

> [card] [Inbox](https://docs.open.cx/inbox/intro.md#translated-macros)
>
> How agents insert macros

> [card] [Real-time translation](https://docs.open.cx/ticketing/real-time-translation.md)
>
> Translate session messages

> [card] [Workspace settings](https://docs.open.cx/ticketing/workspace-settings.md)
>
> Turn suggested macros on or off

> [card] [Macros API](https://docs.open.cx/api-reference/macros/index.md)
>
> Manage macros from your tools


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