Skip to content
Home/
REST API Reference
/
/
Retrieve a macro

Retrieve a macro

Request

You can fetch a single macro (saved reply) by its ID. The macro will only be returned if it is visible to the authenticated user based on its visibility settings.

Visibility Rules

A macro is returned based on its visible_to setting:

  • everyone: Always visible to all team members
  • specific_teams: Only visible if the authenticated user belongs to one of the teams specified in visible_to_team_ids

If a macro exists but is not visible to the authenticated user, a 404 error is returned.

Placeholder Transformation

The API transforms Intercom placeholders to a more standard XML-like format in the body field:

  • From: {{user.name | fallback: 'there'}}
  • To: <attribute key="user.name" default="there"/>

Default values in placeholders are HTML-escaped for security.

Security
bearerAuth
Path
idstringrequired

The unique identifier of the macro

Example:123
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"2.16"
Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.16
/**
 * Requires libcurl
 */

const id = "123";
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <YOUR_TOKEN_HERE>",
    "Intercom-Version: 2.16"
  ],
  CURLOPT_URL => "https://api.intercom.io/macros/" . id,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$error = curl_error($curl);

curl_close($curl);

if ($error) {
  echo "cURL Error #:" . $error;
} else {
  echo $response;
}

Responses

Macro found

Bodyapplication/json
typestring

String representing the object's type. Always has the value macro.

Value:"macro"
Example:"macro"
idstring

The unique identifier for the macro.

Example:"123"
namestring

The name of the macro.

Example:"Order Status Update"
bodystring

The body of the macro in HTML format with placeholders transformed to XML-like format.

Example:"<p>Hi <attribute key=\"user.name\" default=\"there\"/>, your order is ready!</p>"
body_textstring

The plain text version of the macro body with original Intercom placeholder format.

Example:"Hi {{user.name|fallback:\"there\"}}, your order is ready!"
created_atstring, (date-time)

The time the macro was created in ISO 8601 format.

Example:"2025-07-17T11:18:08.000Z"
updated_atstring, (date-time)

The time the macro was last updated in ISO 8601 format.

Example:"2025-07-17T15:30:24.000Z"
visible_tostring

Who can view this macro.

Enum:"everyone""specific_teams"
Example:"everyone"
visible_to_team_idsArray of strings

The team IDs that can view this macro when visible_to is set to specific_teams.

Example:
[
  "456",
  "789"
]
available_onArray of strings

Where the macro is available for use.

Items Enum:"inbox""messenger"
Example:
[
  "inbox",
  "messenger"
]
Response
{
  "type": "macro",
  "id": "789",
  "name": "Refund Process Explanation",
  "body": "<p>Hi <attribute key=\"user.first_name\" default=\"there\"/>,</p><p>I understand you'd like a refund for order #<attribute key=\"conversation.custom_attributes.order_number\"/>. The refund will be processed within 3-5 business days to your <attribute key=\"user.custom_attributes.payment_method\" default=\"original payment method\"/>.</p><p>Is there anything else I can help you with?</p>",
  "body_text": "Hi {{user.first_name|fallback:\"there\"}},\n\nI understand you'd like a refund for order #{{conversation.custom_attributes.order_number}}. The refund will be processed within 3-5 business days to your {{user.custom_attributes.payment_method|fallback:\"original payment method\"}}.\n\nIs there anything else I can help you with?",
  "created_at": "2025-07-21T14:44:35.000Z",
  "updated_at": "2025-07-21T14:44:35.000Z",
  "visible_to": "specific_teams",
  "visible_to_team_ids": [
    "support_team_1",
    "support_team_2"
  ],
  "available_on": [
    "inbox",
    "messenger"
  ]
}