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_idslists 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 a400 - Variables — Read-only. List macro 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. 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 shows the status and text per language, Retranslate a macro redoes them, and Set a macro translation 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_suggestionskeeps 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
stateoflearning,steady,proven,muted, oroff. See List macro suggestion insights - Scopes —
macros:readfor everyGET,macros:writefor everything that changes a macro, the translation languages, or a translation. Create an API key under Settings → API keys. See Authentication
Available Endpoints
List Macros
List every org-wide macro
Get Macro
Fetch one macro by id
Create Macro
Create an org-wide macro
Update Macro
Change any subset of a macro
Delete Macro
Permanently delete a macro
List Macro Variables
The variable names a macro body can use
Get Macro Settings
Read the translation languages and the suggestions switch
Update Macro Settings
Choose the languages macros are translated into
Get Macro Translations
Status and text of one macro’s translations
Retranslate Macro
Translate a macro again
Set Macro Translation
Use your own wording for one language
List Macro Suggestion Insights
How every macro performs as a suggestion
Get Macro Suggestion Insights
The same for one macro, with weekly counts