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

# Macros and canned responses — the inbox reply library

> Build a structured reply library for the inbox. Canned responses store single reusable replies behind a slash shortcut; macros chain replies, assignments, tags, status changes, and follow-ups into one reusable action. Share either across the whole workspace or keep them personal.

# Macros and canned responses — the inbox reply library

Every reply an agent sends more than once belongs in the reply library. The inbox has two levels of it:

* **Canned responses** — single reusable replies. An agent types the shortcut into the composer, and the stored body replaces it. Use them for answers that stay one message: hours, pricing, refund policy, password reset.
* **Macros** — multi-step actions. One macro can send a reply, tag the contact, assign the conversation, set its status, schedule a follow-up message, and open a task — in sequence, with automatic rollback if a step fails. Use them whenever "reply" is really "reply plus three more things."

Both live in the workspace and are created from the dashboard. The search in the macro list resolves by name and shortcut, so a growing library stays findable.

## Where each library lives

Everything below happens around **Inbox**.

| Surface                         | What it holds                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Inbox → Settings → Macros**   | The macro library: create, edit, duplicate, delete macros and organize them into folders.                     |
| **Settings → canned responses** | The quick-reply library: each entry is a shortcut, a title, a body, and an optional channel scope.            |
| **Inbox composer**              | The macro palette and the slash-command palette — where agents apply both libraries to the open conversation. |

## Access scopes — personal vs shared

Every macro and every folder carries a scope that decides who can see and who can change it. The rules are the same as saved views and routing rules elsewhere in the workspace:

* **Personal** — belongs to the agent who created it. Only that agent (or an owner/admin) can edit, delete, or run it. Nobody else sees it in their palette.
* **Team (shared)** — visible to the whole workspace. Only owners and admins can create, edit, or delete a shared macro. Optionally narrow a shared macro to one or more teams, so it renders only for active members of those teams; owners and admins always see the full library.

Folders follow the same split: a personal folder is the creator's private organization layer, a team folder is a shared grouping every agent sees in the palette.

Canned responses are simpler: one org-wide library, managed by owners and admins, usable by every agent in the composer.

## Organize with folders

Folders group macros into collapsible sections in the inbox palette. Manage them on **Inbox → Settings → Macros** from the Folders card:

1. Enter a name in the new-folder field, pick **Personal** or **Team**, and save.
2. Rename or delete a folder from the same card. Deleting a folder never deletes its macros — they fall back to the unfiled bucket.
3. Assign a macro to a folder inside the macro editor; an unassigned macro stays unfiled and is filterable through the folder filter in the library.

## Build a macro

Open **Inbox → Settings → Macros** and create a macro. Each macro has a name, an optional description, and a shortcut — a slash trigger like `refund` the slash-command palette matches. Shortcuts are unique: two shared macros cannot share one, and two of your own personal macros cannot either.

A macro is an ordered list of steps. Add steps, drag them into order with the grip handle (or use the Move up/down buttons), and remove the ones you do not need. The available step types:

| Step                 | What it does                                                                                                        |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Send message         | Sends a reply on the conversation's channel (with an optional media URL).                                           |
| Add tag / Remove tag | Adds or strips contact tags.                                                                                        |
| Assign user          | Assigns the conversation to a teammate — or to `me`, the operator running the macro.                                |
| Set status           | Opens, closes, snoozes, or marks the conversation pending. A snooze with no explicit target falls back to one hour. |
| Snooze               | Snoozes with a required target — an absolute time or a relative offset like `+2h`, `+1d`, `+1w`.                    |
| Set priority         | Sets the conversation's queue priority.                                                                             |
| Set disposition      | Stamps the resolution label from your disposition taxonomy onto the conversation.                                   |
| Schedule follow-up   | Sends a message later — a relative offset (`+1d`) or an absolute time.                                              |
| Create task          | Opens an internal follow-up task, assigned to the conversation's current owner.                                     |
| Escalate to AI agent | Hands the conversation to a named AI agent, with an optional reason and summary.                                    |

Steps run in order. If a step fails, the run reports the failed step and rolls back the reversible steps that already ran — a half-applied macro does not leave the conversation tagged, reassigned, and snoozed around a message that never sent. A few validation rules the editor enforces up front: an empty message body is not savable, one macro cannot set two conflicting priorities or two dispositions, and nothing can snooze a conversation an earlier step already closed.

Running a macro requires a full agent seat. Light seats can read the library but not fire billable steps. Message-sending steps consume credits the same way a hand-typed reply does.

### Variables and placeholders

Message bodies template on mustache-style variables so one shared macro renders correctly for every operator and every contact:

| Variable                                                                                    | Resolves to                                                |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `{{contact.first_name}}`, `{{contact.last_name}}`, `{{contact.email}}`, `{{contact.phone}}` | The contact's profile fields.                              |
| `{{contact.custom.<field>}}`                                                                | A custom field on the contact, addressed by its key.       |
| `{{agent.name}}`, `{{agent.signature}}`                                                     | The running agent's name, and their saved inbox signature. |
| `{{conversation.id}}`                                                                       | The conversation the macro runs against.                   |

Anything that does not resolve renders as an empty string — a typo shows up as a missing word in the editor's live preview, not as a literal `{{...}}` in a customer-facing message. The editor renders the preview against a sample contact while you type, so verify the placeholders before saving.

### Per-locale message bodies

The body of a **Send message** or **Schedule follow-up** step can carry one version per language. The editor defaults to tabs for English, Spanish, and French; the English body is the required fallback. When the macro runs, it picks the body that matches the conversation's detected language — falling back to the contact's stored language, then to English — so one "refund policy" macro serves a multilingual queue.

### Channel-specific canned responses

A canned response can be scoped to a channel — SMS, WhatsApp, email — or left channel-agnostic. The composer only offers entries valid for the open conversation's channel: the channel-specific entries for that channel plus the channel-agnostic ones. Scope a response to SMS when the body must fit a segment budget, and keep the longer version scoped to email.

## Apply from the composer

Three entry points, all on the open conversation:

1. **Macro palette** — the palette attached to the composer lists the macros visible to you, grouped by folder, with your most-used macros ranked by your own recent run count.
2. **Slash command — `/template <name-or-shortcut>`** — press `/` with a conversation open, then pick the macro from the filtered list.
3. **Canned response shortcut** — type the entry's slash shortcut into the composer text and the stored body replaces it.

Multi-step macros show a preview before they fire: every step rendered against the live conversation — variables interpolated, the language-specific body picked, relative times (`+2h`) converted to exact timestamps — with zero side effects until you confirm. This is the operator's last check before a run that sends messages and bills credits; use it. Once fired, re-running the same macro against the same conversation inside 30 seconds is debounced, so a double click cannot double-send.

## Example: a refund-policy macro

A support team handles refund questions across SMS and WhatsApp. The owner builds a shared macro named **Refund policy** with the shortcut `/refund`, filed under a team folder called **Policies**:

1. **Send message** — English body: `Hi {{contact.first_name}}, our refund policy: full refunds within 30 days of purchase, no questions asked. {{agent.signature}}` — with a Spanish body on the `es` tab: `Hola {{contact.first_name}}, nuestra política de reembolso: reembolso completo dentro de los 30 días de la compra. {{agent.signature}}`
2. **Add tag** — `refund-explained`.
3. **Snooze** — `+2d`, so the thread reopens if the customer does not reply.
4. **Set disposition** — the `refund-policy` label from the workspace taxonomy.

The scope decision shows the access levels in practice:

* An agent who wants the same chain for themselves only creates it as a **personal** macro — visible and runnable by that agent alone.
* A team lead narrows a **shared** macro to the support team, so refund-handling templates never clutter the sales team's palette.
* The workspace owner publishes the macro **shared with no team narrowing** — every agent can run it, and only owners and admins can change the wording once legal has reviewed it.

Preview against an open conversation before saving the shared version: you see the exact message body that will leave the workspace, the tag applied, the snooze target resolved to an exact time, and the disposition label — before any customer sees anything.