​

Canned responses and macros — the reply library model

• A canned response is a named template blob — one reusable message body stored under a shortcut. It is content only: a shortcut like /hours, a title, a body, and an optional channel scope. When an agent types the shortcut in the composer, the stored body replaces it.
• A macro is a canned response plus more: an ordered chain of steps — send a message, add or remove contact tags, assign the conversation, set its status or priority, snooze it, schedule a follow-up, create a task, or escalate to an AI agent. The message step of a macro carries variable placeholders ({{contact.first_name}}, {{agent.signature}}) that resolve against the live conversation when the macro runs.

​

Scoping — who can see and run each

• Personal macros belong to the agent who created them. Only the creator (or an owner/admin) can edit, delete, or run them, and nobody else sees them in the palette or the list.
• Team (shared) macros are created by owners and admins and are readable by everyone in the workspace. Optionally the creator narrows a shared macro to one or more team ids; then only active members of the listed teams see it in their palette. Owners and admins bypass the narrowing and always see the full library.

​

How resolution works at send time

1. Lookup. Running a macro loads the stored definition, which is the placeholder map against the current conversation.
2. Variable interpolation. {{contact.*}} fields resolve from the contact profile, {{agent.*}} from the running agent’s saved signature and name, {{conversation.*}} from the conversation the macro runs against. Anything that does not resolve renders as an empty string — a typo shows up as a missing word, not as a literal {{...}} in a customer-facing message.
3. Locale selection. A message step can carry one body per language. The run picks the body matching the conversation’s detected language, falls back to the contact’s stored language, then to English (the required fallback body). One “refund policy” macro serves a multilingual queue.
4. Preview before commit. Multi-step macros render every step against the live conversation — variables interpolated, relative times converted to exact timestamps — with zero side effects until the operator confirms. Once fired, re-running the same macro against the same conversation inside 30 seconds is debounced, so a double click cannot double-send.

​

Where the library appears

• Inbox — the operator picker. The macro palette attached to the composer lists the macros visible to the current agent, grouped by folder, ranked by their own recent run count. Canned responses are reachable through the slash shortcut typed into the composer text. Both are the day-to-day surface.
• Campaigns — the template step. A campaign that needs a reusable body references a carrier-reviewed template by id; a canned response is not a campaign object. The distinction matters: campaigns go through the template lifecycle because they send at scale, while inbox replies go through the reply library because agents send them one conversation at a time.
• Flows — automation steps that send messages resolve the same way a macro’s message step does: either reference an approved template or carry an inline body on a platform-only channel.

​

A worked example

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/canned-responses" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "shortcut": "/refund-sms",
    "title": "Refund policy (SMS)",
    "content": "Our refund policy: full refunds within 30 days, no questions asked.",
    "channel": "sms"
  }'

​

See also

• Macros and canned responses guide — the operator walkthrough for building, organizing, and applying both libraries
• Template lifecycle and approval semantics — the carrier-review model macro message steps reference on approval-required channels
• Settings API reference — the canned-response CRUD contract