From c9788ddd2a980e379ee0a9dacf4725003008d951 Mon Sep 17 00:00:00 2001 From: Levin Dixon Date: Mon, 28 Jul 2025 16:53:23 +0100 Subject: [PATCH 1/8] feat(api): Add Macro schema definition to OpenAPI spec (intercom/intercom#420117) Add the Macro object schema to the Unstable API specification. This schema represents saved replies (macros) that can be used for quick responses in conversations. Schema includes: - Basic fields: type, id, name - Content fields: body (HTML with transformed placeholders), body_text - Timestamps: created_at, updated_at (Unix timestamps) - Visibility controls: visible_to, visible_to_team_ids - Availability: available_on array for inbox/messenger The schema follows the implementation in MacroPresenter and includes the placeholder transformation feature where mustache-style placeholders are converted to XML-like attribute tags. Part of: intercom/intercom#420117 --- descriptions/0/api.intercom.io.yaml | 71 +++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f90b489..f4fdb22 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -18702,6 +18702,77 @@ components: description: An array containing the linked conversations and linked tickets. items: "$ref": "#/components/schemas/linked_object" + macro: + title: Macro + type: object + x-tags: + - Unstable + description: A macro is a pre-defined response template (saved reply) that can be used to quickly reply to conversations. + nullable: true + properties: + type: + type: string + description: String representing the object's type. Always has the value `macro`. + enum: + - macro + example: macro + id: + type: string + description: The unique identifier for the macro. + example: "123" + name: + type: string + description: The name of the macro. + example: "Order Status Update" + body: + type: string + description: The body of the macro in HTML format with placeholders transformed to XML-like format. + example: "

Hi , your order is ready!

" + body_text: + type: string + description: The plain text version of the macro body. + example: "Hi there, your order is ready!" + created_at: + type: integer + format: int64 + description: The time the macro was created as a Unix timestamp. + example: 1719474966 + updated_at: + type: integer + format: int64 + description: The time the macro was last updated as a Unix timestamp. + example: 1719493757 + visible_to: + type: string + description: Who can view this macro. + enum: + - everyone + - specific_teams + example: everyone + visible_to_team_ids: + type: array + description: The team IDs that can view this macro when visible_to is set to specific_teams. + items: + type: string + example: ["456", "789"] + available_on: + type: array + description: Where the macro is available for use. + items: + type: string + enum: + - inbox + - messenger + example: ["inbox", "messenger"] + required: + - type + - id + - name + - body + - created_at + - updated_at + - visible_to + - available_on merge_contacts_request: description: Merge contact data. type: object From 768eb369569a34e4ff2fec74bbd1ed5d4d99c06e Mon Sep 17 00:00:00 2001 From: Levin Dixon Date: Mon, 28 Jul 2025 17:23:07 +0100 Subject: [PATCH 2/8] feat: Add MacroList schema for paginated macro responses (intercom/intercom#420117) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add MacroList schema to support paginated list responses for macros - Follow established pattern with type "list" and data array - Implement cursor-based pagination with starting_after parameter - Include Base64-encoded cursor for stable pagination ([updated_at, id] tuples) - Reference existing macro schema for data items - Add x-tags: Unstable to match macro visibility This schema will be used by the GET /macros endpoint to return paginated lists of saved reply templates. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 50 +++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f4fdb22..bd34700 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -18773,6 +18773,56 @@ components: - updated_at - visible_to - available_on + macro_list: + title: Macro List + type: object + x-tags: + - Unstable + description: A paginated list of macros (saved replies) in the workspace. + properties: + type: + type: string + description: Always list + enum: + - list + example: list + data: + type: array + description: The list of macro objects + items: + "$ref": "#/components/schemas/macro" + pages: + type: object + description: Pagination information + properties: + type: + type: string + description: The type of pagination + enum: + - pages + example: pages + per_page: + type: integer + description: Number of results per page + example: 50 + next: + type: object + nullable: true + description: Cursor for the next page + properties: + starting_after: + type: string + description: Base64-encoded cursor containing [updated_at, id] for pagination + example: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd" + required: + - starting_after + required: + - type + - per_page + required: + - type + - data + - pages merge_contacts_request: description: Merge contact data. type: object From 0901716f7ed392fc03969d9c1f54c39e2ca095f6 Mon Sep 17 00:00:00 2001 From: Levin Dixon Date: Mon, 28 Jul 2025 18:22:07 +0100 Subject: [PATCH 3/8] feat(api): Add Macros API endpoints to OpenAPI spec (intercom/intercom#420117) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add GET /macros and GET /macros/{id} endpoint definitions to the Unstable OpenAPI specification for the new Macros API. Changes: - Add GET /macros endpoint with cursor-based pagination - Query parameters: per_page (1-150, default 50), starting_after (Base64 cursor), updated_since (Unix timestamp) - Returns paginated list of macros with MacroList schema - Documents placeholder transformation from Intercom to XML-like format - Add GET /macros/{id} endpoint for single macro retrieval - Path parameter: id (macro identifier) - Returns single macro with Macro schema - Add Macros tag to tags section in alphabetical order - Include comprehensive examples and error responses (400, 401, 403, 404) - Document OAuth scope requirement (read_conversations) The endpoints follow existing patterns in the OpenAPI spec and accurately reflect the implementation in PR #419604. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 206 ++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index bd34700..183520e 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -9211,6 +9211,210 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/macros": + get: + summary: List all macros + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: per_page + in: query + schema: + type: integer + minimum: 1 + maximum: 150 + default: 50 + description: The number of results per page + example: 50 + - name: starting_after + in: query + schema: + type: string + description: Base64-encoded cursor containing [updated_at, id] for pagination + example: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd" + - name: updated_since + in: query + schema: + type: integer + format: int64 + description: Unix timestamp to filter macros updated after this time + example: 1719474966 + tags: + - Macros + operationId: listMacros + description: | + You can fetch a list of all macros (saved replies) in your workspace for use in automating responses. + + The macros are returned in descending order by updated_at. + + **Pagination** + + This endpoint uses cursor-based pagination via the `starting_after` parameter. The cursor is a Base64-encoded JSON array containing `[updated_at, id]` of the last item from the previous page. + + **Placeholder Transformation** + + The API transforms Intercom placeholders to a more standard XML-like format: + - From: `{{user.name | fallback: 'there'}}` + - To: `` + responses: + '200': + description: Successful response + content: + application/json: + examples: + Successful response: + value: + type: list + data: + - type: macro + id: "123" + name: "Order Status Update" + body: "

Hi , your order # is ready!

" + body_text: "Hi there, your order is ready!" + created_at: 1719474966 + updated_at: 1719493757 + visible_to: "everyone" + visible_to_team_ids: [] + available_on: ["inbox", "messenger"] + pages: + type: pages + per_page: 50 + next: + starting_after: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd" + schema: + "$ref": "#/components/schemas/macro_list" + '400': + description: Bad Request + content: + application/json: + examples: + Invalid parameter: + value: + type: error.list + request_id: bc300b1a-492a-405f-924e-a5881cb72e3a + errors: + - code: parameter_invalid + message: Invalid updated_since timestamp + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden - missing required OAuth scope + content: + application/json: + examples: + Missing scope: + value: + type: error.list + request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef + errors: + - code: forbidden + message: Token does not have the required 'read_conversations' scope + schema: + "$ref": "#/components/schemas/error" + "/macros/{id}": + get: + summary: Retrieve a macro + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The ID of the macro to retrieve + schema: + type: string + example: "123" + tags: + - Macros + operationId: getMacro + description: | + You can fetch a single macro by its ID. + + **Placeholder Transformation** + + The API transforms Intercom placeholders to a more standard XML-like format: + - From: `{{user.name | fallback: 'there'}}` + - To: `` + responses: + '200': + description: Macro found + content: + application/json: + examples: + Macro found: + value: + type: macro + id: "123" + name: "Order Status Update" + body: "

Hi , your order # is ready!

" + body_text: "Hi there, your order is ready!" + created_at: 1719474966 + updated_at: 1719493757 + visible_to: "everyone" + visible_to_team_ids: [] + available_on: ["inbox", "messenger"] + schema: + "$ref": "#/components/schemas/macro" + '404': + description: Macro not found + content: + application/json: + examples: + Macro not found: + value: + type: error.list + request_id: bc300b1a-492a-405f-924e-a5881cb72e3a + errors: + - code: not_found + message: Macro not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden - missing required OAuth scope + content: + application/json: + examples: + Missing scope: + value: + type: error.list + request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef + errors: + - code: forbidden + message: Token does not have the required 'read_conversations' scope + schema: + "$ref": "#/components/schemas/error" "/messages": post: summary: Create a message @@ -21526,6 +21730,8 @@ tags: description: Everything about your Help Center - name: Jobs description: Everything about jobs +- name: Macros + description: Everything about your Macros (Saved Replies) - name: Messages description: Everything about your messages - name: News From d9c0e717562b2537559270ac2792f624ca286706 Mon Sep 17 00:00:00 2001 From: Levin Dixon Date: Mon, 28 Jul 2025 19:16:17 +0100 Subject: [PATCH 4/8] docs(api): Enhance macro retrieval endpoint documentation (intercom/intercom#420117) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Clarify macro visibility rules and team-based access control - Add detailed explanation of when macros are accessible vs return 404 - Expand examples to show team-restricted and complex placeholder scenarios - Document HTML escaping behavior for placeholder default values - Improve parameter description for clarity 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 74 +++++++++++++++++++++-------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 183520e..9b0ed15 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -9338,7 +9338,7 @@ paths: - name: id in: path required: true - description: The ID of the macro to retrieve + description: The unique identifier of the macro schema: type: string example: "123" @@ -9346,47 +9346,67 @@ paths: - Macros operationId: getMacro description: | - You can fetch a single macro by its ID. + 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: + The API transforms Intercom placeholders to a more standard XML-like format in the `body` field: - From: `{{user.name | fallback: 'there'}}` - To: `` + + Default values in placeholders are HTML-escaped for security. responses: '200': description: Macro found content: application/json: examples: - Macro found: + Macro visible to everyone: value: type: macro id: "123" name: "Order Status Update" - body: "

Hi , your order # is ready!

" - body_text: "Hi there, your order is ready!" + body: "

Hi , your order # is ready for pickup!

" + body_text: "Hi there, your order is ready for pickup!" created_at: 1719474966 updated_at: 1719493757 visible_to: "everyone" visible_to_team_ids: [] available_on: ["inbox", "messenger"] - schema: - "$ref": "#/components/schemas/macro" - '404': - description: Macro not found - content: - application/json: - examples: - Macro not found: + Macro with team restrictions: value: - type: error.list - request_id: bc300b1a-492a-405f-924e-a5881cb72e3a - errors: - - code: not_found - message: Macro not found + type: macro + id: "456" + name: "VIP Customer Support" + body: "

Dear , we appreciate your VIP status. Your dedicated support team is here to help.

" + body_text: "Dear valued customer, we appreciate your VIP status. Your dedicated support team is here to help." + created_at: 1719474966 + updated_at: 1719493757 + visible_to: "specific_teams" + visible_to_team_ids: ["789", "012"] + available_on: ["inbox"] + Macro with complex placeholders: + value: + type: macro + id: "789" + name: "Account Summary" + body: "

Hello !

Your account balance is .

Last login:

" + body_text: "Hello there! Your account balance is not available. Last login: never" + created_at: 1719474966 + updated_at: 1719493757 + visible_to: "everyone" + visible_to_team_ids: [] + available_on: ["inbox", "messenger"] schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/macro" '401': description: Unauthorized content: @@ -9415,6 +9435,20 @@ paths: message: Token does not have the required 'read_conversations' scope schema: "$ref": "#/components/schemas/error" + '404': + description: Macro not found or not accessible + content: + application/json: + examples: + Macro not found: + value: + type: error.list + request_id: bc300b1a-492a-405f-924e-a5881cb72e3a + errors: + - code: not_found + message: Macro not found + schema: + "$ref": "#/components/schemas/error" "/messages": post: summary: Create a message From cc7c664eb0d871054218c91cb085aeb8d6901b85 Mon Sep 17 00:00:00 2001 From: Levin Dixon Date: Mon, 28 Jul 2025 23:53:42 +0100 Subject: [PATCH 5/8] feat(postman): Add Macros API collection with comprehensive examples (intercom/intercom#420117) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add complete Postman collection for the new Macros API endpoints including: - List all macros endpoint with basic pagination - List macros with cursor-based pagination example - List macros filtered by update timestamp - Complex example combining multiple query parameters - Get single macro by ID with error responses Each request includes: - Proper Bearer token authentication setup - Required Intercom-Version header for Unstable API - Detailed parameter descriptions and usage notes - Example responses showcasing placeholder transformation - Test scripts for response validation and cursor handling The collection provides developers with executable examples to quickly test and integrate the Macros API without writing code first. 🤖 Generated with Claude Code Co-Authored-By: Claude --- .../intercom-api.postman_collection.json | 402 ++++++++++++++++++ 1 file changed, 402 insertions(+) diff --git a/postman/Unstable/intercom-api.postman_collection.json b/postman/Unstable/intercom-api.postman_collection.json index 58a8b4a..531f1dc 100644 --- a/postman/Unstable/intercom-api.postman_collection.json +++ b/postman/Unstable/intercom-api.postman_collection.json @@ -5393,6 +5393,408 @@ } ] }, + { + "name": "Macros", + "description": "Programmatic access to saved replies (macros) in Intercom. Use these endpoints to retrieve pre-written responses for integration with third-party tools and workflows.\n\n**OAuth Scope Required**: `READ_CONVERSATIONS`\n\n**Key Features**:\n- Cursor-based pagination for efficient data retrieval\n- Automatic placeholder transformation (Intercom format → XML attributes)\n- Filtering by update timestamp\n- Respects team visibility settings", + "item": [ + { + "name": "List all macros", + "tags": [ + "Macros" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/macros?per_page=25", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "macros" + ], + "query": [ + { + "key": "per_page", + "value": "25", + "description": "Number of macros to return per page (max 150)" + } + ], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "GET", + "description": "Retrieves a paginated list of all macros available to the authenticated user. Returns up to 25 macros per page.\n\n**Response includes**:\n- Macro details (id, name, body with transformed placeholders)\n- Visibility settings and team assignments\n- Channel availability (inbox/messenger)\n- Pagination cursor for retrieving additional pages", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [ + { + "name": "Successful response", + "status": "OK", + "code": 200, + "_postman_previewlanguage": "json", + "header": [], + "cookie": [], + "body": "{\n \"type\": \"list\",\n \"data\": [\n {\n \"type\": \"macro\",\n \"id\": \"123\",\n \"name\": \"Welcome Message\",\n \"body\": \"

Hi , welcome to our service!

\",\n \"body_text\": \"Hi there, welcome to our service!\",\n \"created_at\": 1719474966,\n \"updated_at\": 1719493757,\n \"visible_to\": \"everyone\",\n \"visible_to_team_ids\": [],\n \"available_on\": [\"inbox\", \"messenger\"]\n }\n ],\n \"pages\": {\n \"type\": \"pages\",\n \"per_page\": 25,\n \"next\": {\n \"starting_after\": \"WzE3MTk0OTM3NTcuMCwgIjEyMyJd\"\n }\n }\n}" + } + ] + }, + { + "name": "List macros (with pagination)", + "tags": [ + "Macros" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/macros?per_page=50&starting_after=WzE3MTk0OTM3NTcuMCwgIjEyMyJd", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "macros" + ], + "query": [ + { + "key": "per_page", + "value": "50", + "description": "Number of macros to return per page (max 150)" + }, + { + "key": "starting_after", + "value": "WzE3MTk0OTM3NTcuMCwgIjEyMyJd", + "description": "Cursor from previous response's pages.next.starting_after" + } + ], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "GET", + "description": "Demonstrates cursor-based pagination. Use the `starting_after` cursor from a previous response to retrieve the next page of results.\n\n**Important**: The cursor encodes `[updated_at, id]` to ensure stable ordering even as macros are modified.", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + }, + { + "name": "List macros (updated since)", + "tags": [ + "Macros" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/macros?updated_since=1719474966", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "macros" + ], + "query": [ + { + "key": "updated_since", + "value": "1719474966", + "description": "Unix timestamp - only return macros updated after this time" + } + ], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "GET", + "description": "Efficiently sync recently modified macros by filtering with the `updated_since` parameter. Useful for:\n- Incremental synchronization with external systems\n- Tracking macro changes over time\n- Reducing API calls for large macro libraries", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + }, + { + "name": "List macros (complex example)", + "tags": [ + "Macros" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/macros?per_page=100&updated_since=1719474966&starting_after=WzE3MTk0OTM3NTcuMCwgIjQ1NiJd", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "macros" + ], + "query": [ + { + "key": "per_page", + "value": "100", + "description": "Retrieve up to 100 macros per request" + }, + { + "key": "updated_since", + "value": "1719474966", + "description": "Filter to macros updated after this timestamp" + }, + { + "key": "starting_after", + "value": "WzE3MTk0OTM3NTcuMCwgIjQ1NiJd", + "description": "Continue pagination from previous request" + } + ], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "GET", + "description": "Combines multiple parameters for advanced use cases:\n- Large batch retrieval (100 items)\n- Filtered by update time\n- With pagination continuation\n\nThis pattern is ideal for initial sync followed by incremental updates.", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + }, + { + "name": "Get a macro", + "tags": [ + "Macros" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/macros/:id", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "macros", + ":id" + ], + "query": [], + "variable": [ + { + "key": "id", + "value": "123", + "disabled": false, + "description": "The ID of the macro to retrieve" + } + ] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "GET", + "description": "Retrieves a single macro by its ID. Use this endpoint when you need:\n- Full details of a specific macro\n- To verify a macro still exists\n- To check for updates to a known macro\n\n**Note**: Returns 404 if the macro doesn't exist or isn't visible to the authenticated user.", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [ + { + "name": "Successful response", + "status": "OK", + "code": 200, + "_postman_previewlanguage": "json", + "header": [], + "cookie": [], + "body": "{\n \"type\": \"macro\",\n \"id\": \"123\",\n \"name\": \"Order Confirmation\",\n \"body\": \"

Thank you for your order, !

Order # has been confirmed.

\",\n \"body_text\": \"Thank you for your order, valued customer!\\n\\nOrder # has been confirmed.\",\n \"created_at\": 1719474966,\n \"updated_at\": 1719493757,\n \"visible_to\": \"selected_teams\",\n \"visible_to_team_ids\": [456, 789],\n \"available_on\": [\"inbox\"]\n}" + }, + { + "name": "Not found", + "status": "Not Found", + "code": 404, + "_postman_previewlanguage": "json", + "header": [], + "cookie": [], + "body": "{\n \"type\": \"error.list\",\n \"errors\": [\n {\n \"code\": \"not_found\",\n \"message\": \"Macro not found\"\n }\n ]\n}" + } + ] + } + ], + "event": [ + { + "listen": "prerequest", + "script": { + "type": "text/javascript", + "exec": [ + "// Ensure Intercom-Version header is set for Unstable API", + "pm.request.headers.add({", + " key: 'Intercom-Version',", + " value: 'Unstable'", + "});" + ] + } + }, + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [ + "// Example test for List all macros", + "pm.test(\"Status code is 200\", function () {", + " pm.response.to.have.status(200);", + "});", + "", + "pm.test(\"Response has correct structure\", function () {", + " var jsonData = pm.response.json();", + " pm.expect(jsonData).to.have.property('type', 'list');", + " pm.expect(jsonData).to.have.property('data');", + " pm.expect(jsonData).to.have.property('pages');", + "});", + "", + "pm.test(\"Macros have transformed placeholders\", function () {", + " var jsonData = pm.response.json();", + " if (jsonData.data && jsonData.data.length > 0) {", + " var macro = jsonData.data[0];", + " if (macro.body && macro.body.includes('{{')) {", + " pm.expect(macro.body).to.include('` + + Note: The `body_text` field retains the original Intercom placeholder format. responses: '200': description: Successful response @@ -9272,9 +9274,9 @@ paths: id: "123" name: "Order Status Update" body: "

Hi , your order # is ready!

" - body_text: "Hi there, your order is ready!" - created_at: 1719474966 - updated_at: 1719493757 + body_text: "Hi {{user.name|fallback:\"there\"}}, your order is ready!" + created_at: "2025-07-17T11:18:08.000Z" + updated_at: "2025-07-17T15:30:24.000Z" visible_to: "everyone" visible_to_team_ids: [] available_on: ["inbox", "messenger"] @@ -9358,10 +9360,11 @@ paths: **Placeholder Transformation** - The API transforms Intercom placeholders to a more standard XML-like format in the `body` field: + The API transforms Intercom placeholders in the `body` field to a more standard XML-like format: - From: `{{user.name | fallback: 'there'}}` - To: `` + Note: The `body_text` field retains the original Intercom placeholder format. Default values in placeholders are HTML-escaped for security. responses: '200': @@ -9375,9 +9378,9 @@ paths: id: "123" name: "Order Status Update" body: "

Hi , your order # is ready for pickup!

" - body_text: "Hi there, your order is ready for pickup!" - created_at: 1719474966 - updated_at: 1719493757 + body_text: "Hi {{user.name|fallback:\"there\"}}, your order is ready for pickup!" + created_at: "2025-07-17T11:18:08.000Z" + updated_at: "2025-07-17T15:30:24.000Z" visible_to: "everyone" visible_to_team_ids: [] available_on: ["inbox", "messenger"] @@ -9387,9 +9390,9 @@ paths: id: "456" name: "VIP Customer Support" body: "

Dear , we appreciate your VIP status. Your dedicated support team is here to help.

" - body_text: "Dear valued customer, we appreciate your VIP status. Your dedicated support team is here to help." - created_at: 1719474966 - updated_at: 1719493757 + body_text: "Dear {{user.name|fallback:\"valued customer\"}}, we appreciate your VIP status. Your dedicated support team is here to help." + created_at: "2025-07-17T11:18:08.000Z" + updated_at: "2025-07-17T15:30:24.000Z" visible_to: "specific_teams" visible_to_team_ids: ["789", "012"] available_on: ["inbox"] @@ -9399,9 +9402,9 @@ paths: id: "789" name: "Account Summary" body: "

Hello !

Your account balance is .

Last login:

" - body_text: "Hello there! Your account balance is not available. Last login: never" - created_at: 1719474966 - updated_at: 1719493757 + body_text: "Hello {{user.name|fallback:\"there\"}}! Your account balance is {{account.balance|fallback:\"not available\"}}. Last login: {{user.last_login|fallback:\"never\"}}" + created_at: "2025-07-17T11:18:08.000Z" + updated_at: "2025-07-17T15:30:24.000Z" visible_to: "everyone" visible_to_team_ids: [] available_on: ["inbox", "messenger"] @@ -18968,18 +18971,18 @@ components: example: "

Hi , your order is ready!

" body_text: type: string - description: The plain text version of the macro body. - example: "Hi there, your order is ready!" + description: The plain text version of the macro body with original Intercom placeholder format. + example: "Hi {{user.name|fallback:\"there\"}}, your order is ready!" created_at: - type: integer - format: int64 - description: The time the macro was created as a Unix timestamp. - example: 1719474966 + type: string + format: date-time + description: The time the macro was created in ISO 8601 format. + example: "2025-07-17T11:18:08.000Z" updated_at: - type: integer - format: int64 - description: The time the macro was last updated as a Unix timestamp. - example: 1719493757 + type: string + format: date-time + description: The time the macro was last updated in ISO 8601 format. + example: "2025-07-17T15:30:24.000Z" visible_to: type: string description: Who can view this macro. @@ -19007,9 +19010,11 @@ components: - id - name - body + - body_text - created_at - updated_at - visible_to + - visible_to_team_ids - available_on macro_list: title: Macro List diff --git a/postman/Unstable/README.md b/postman/Unstable/README.md index 49b48d5..657d53c 100644 --- a/postman/Unstable/README.md +++ b/postman/Unstable/README.md @@ -12,4 +12,4 @@ This directory contains the Postman collection for Intercom API version Unstable 3. Set your access token in the environment variables 4. Start making API calls! -Last updated: 2025-04-25T10:49:24.297Z +Last updated: 2025-07-31T07:41:44.918Z diff --git a/postman/Unstable/intercom-api.postman_collection.json b/postman/Unstable/intercom-api.postman_collection.json index 531f1dc..4da4790 100644 --- a/postman/Unstable/intercom-api.postman_collection.json +++ b/postman/Unstable/intercom-api.postman_collection.json @@ -8,7 +8,7 @@ "url": "https://developers.intercom.com" }, "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", - "updatedAt": "2025-04-25T10:49:24.294Z" + "updatedAt": "2025-07-31T07:41:44.914Z" }, "item": [ { @@ -3396,7 +3396,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"message_type\": \"comment\",\n \"type\": \"admin\",\n \"body\": \"Hello there!\",\n \"created_at\": 1590000000,\n \"attachment_urls\": \"\",\n \"admin_id\": \"3156780\",\n \"reply_options\": [\n {\n \"text\": \"\",\n \"uuid\": \"\"\n }\n ],\n \"attachment_files\": [\n {\n \"content_type\": \"application/json\",\n \"data\": \"ewogICJ0ZXN0IjogMQp9\",\n \"name\": \"test.json\"\n }\n ]\n}", + "raw": "{\n \"message_type\": \"comment\",\n \"type\": \"admin\",\n \"body\": \"Hello there!\",\n \"created_at\": 1590000000,\n \"attachment_urls\": \"\",\n \"reply_options\": [\n {\n \"text\": \"\",\n \"uuid\": \"\"\n }\n ],\n \"admin_id\": \"3156780\",\n \"attachment_files\": [\n {\n \"content_type\": \"application/json\",\n \"data\": \"ewogICJ0ZXN0IjogMQp9\",\n \"name\": \"test.json\"\n }\n ]\n}", "urlencoded": [], "formdata": [] } @@ -3754,7 +3754,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"read\": true,\n \"title\": \"Conversation Title\",\n \"custom_attributes\": {\n \"paid_subscriber\": true,\n \"monthly_spend\": 155.5,\n \"team_mates\": 9,\n \"start_date_iso8601\": \"2023-03-04T09:46:14Z\",\n \"end_date_timestamp\": 1677923174\n }\n}", + "raw": "{\n \"read\": true,\n \"title\": \"Conversation Title\",\n \"custom_attributes\": {\n \"paid_subscriber\": true,\n \"monthly_spend\": 155.5,\n \"team_mates\": 9,\n \"start_date_iso8601\": \"2023-03-04T09:46:14Z\",\n \"end_date_timestamp\": 1677923174\n },\n \"company_id\": \"5f4d3c1c-7b1b-4d7d-a97e-6095715c6632\"\n}", "urlencoded": [], "formdata": [] } @@ -3904,6 +3904,267 @@ } ] }, + { + "name": "Custom Channel Events", + "item": [ + { + "name": "Notify Intercom of a new conversation created in a custom channel", + "tags": [ + "Custom Channel Events" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/custom_channel_events/notify_new_conversation", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "custom_channel_events", + "notify_new_conversation" + ], + "query": [], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "POST", + "description": "Notifies Intercom that a new conversation was created in your custom channel/platform. This triggers conversation creation and workflow automations within Intercom for your custom channel integration.\n> **Note:** This endpoint is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support.\n", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"event_id\": \"\",\n \"external_conversation_id\": \"\",\n \"contact\": {\n \"type\": \"user\",\n \"external_id\": \"\",\n \"name\": \"\",\n \"email\": \"\"\n }\n}", + "urlencoded": [], + "formdata": [] + } + }, + "response": [] + }, + { + "name": "Notify Intercom of a new message in a custom channel conversation", + "tags": [ + "Custom Channel Events" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/custom_channel_events/notify_new_message", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "custom_channel_events", + "notify_new_message" + ], + "query": [], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "POST", + "description": "Notifies Intercom that a new message was sent in a conversation on your custom channel/platform. This allows Intercom to process the message and trigger any relevant workflow automations.\n> **Note:** This endpoint is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support.\n", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"event_id\": \"\",\n \"external_conversation_id\": \"\",\n \"contact\": {\n \"type\": \"user\",\n \"external_id\": \"\",\n \"name\": \"\",\n \"email\": \"\"\n },\n \"body\": \"\"\n}", + "urlencoded": [], + "formdata": [] + } + }, + "response": [] + }, + { + "name": "Notify Intercom of a quick reply response in a custom channel conversation", + "tags": [ + "Custom Channel Events" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/custom_channel_events/notify_quick_reply_selected", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "custom_channel_events", + "notify_quick_reply_selected" + ], + "query": [], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "POST", + "description": "Notifies Intercom that a user selected a quick reply option in your custom channel/platform. This allows Intercom to process the response and trigger any relevant workflow automations.\n> **Note:** This endpoint is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support.\n", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"event_id\": \"\",\n \"external_conversation_id\": \"\",\n \"contact\": {\n \"type\": \"user\",\n \"external_id\": \"\",\n \"name\": \"\",\n \"email\": \"\"\n },\n \"quick_reply_option_id\": \"\"\n}", + "urlencoded": [], + "formdata": [] + } + }, + "response": [] + }, + { + "name": "Notify Intercom of an attribute collector response in a custom channel conversation", + "tags": [ + "Custom Channel Events" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/custom_channel_events/notify_attribute_collected", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "custom_channel_events", + "notify_attribute_collected" + ], + "query": [], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "POST", + "description": "Notifies Intercom that a user provided a response to an attribute collector in your custom channel/platform. This allows Intercom to process the attribute and trigger any relevant workflow automations.\n> **Note:** This endpoint is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support.\n", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"event_id\": \"\",\n \"external_conversation_id\": \"\",\n \"contact\": {\n \"type\": \"user\",\n \"external_id\": \"\",\n \"name\": \"\",\n \"email\": \"\"\n },\n \"attribute\": {\n \"id\": \"\",\n \"value\": \"\"\n }\n}", + "urlencoded": [], + "formdata": [] + } + }, + "response": [] + } + ] + }, { "name": "Custom Object Instances", "item": [ @@ -5395,7 +5656,6 @@ }, { "name": "Macros", - "description": "Programmatic access to saved replies (macros) in Intercom. Use these endpoints to retrieve pre-written responses for integration with third-party tools and workflows.\n\n**OAuth Scope Required**: `READ_CONVERSATIONS`\n\n**Key Features**:\n- Cursor-based pagination for efficient data retrieval\n- Automatic placeholder transformation (Intercom format → XML attributes)\n- Filtering by update timestamp\n- Respects team visibility settings", "item": [ { "name": "List all macros", @@ -5404,77 +5664,7 @@ ], "request": { "url": { - "raw": "https://api.intercom.io/macros?per_page=25", - "protocol": "https", - "host": [ - "api.intercom.io" - ], - "path": [ - "macros" - ], - "query": [ - { - "key": "per_page", - "value": "25", - "description": "Number of macros to return per page (max 150)" - } - ], - "variable": [] - }, - "auth": { - "type": "bearer", - "bearer": [ - { - "key": "bearerToken", - "value": "{{bearerToken}}", - "type": "string" - }, - { - "key": "tokenType", - "value": "bearer", - "type": "string" - }, - { - "key": "addTokenTo", - "value": "header", - "type": "string" - } - ] - }, - "method": "GET", - "description": "Retrieves a paginated list of all macros available to the authenticated user. Returns up to 25 macros per page.\n\n**Response includes**:\n- Macro details (id, name, body with transformed placeholders)\n- Visibility settings and team assignments\n- Channel availability (inbox/messenger)\n- Pagination cursor for retrieving additional pages", - "header": [ - { - "key": "Intercom-Version", - "value": "Unstable" - }, - { - "key": "Accept", - "value": "application/json" - } - ], - "body": null - }, - "response": [ - { - "name": "Successful response", - "status": "OK", - "code": 200, - "_postman_previewlanguage": "json", - "header": [], - "cookie": [], - "body": "{\n \"type\": \"list\",\n \"data\": [\n {\n \"type\": \"macro\",\n \"id\": \"123\",\n \"name\": \"Welcome Message\",\n \"body\": \"

Hi , welcome to our service!

\",\n \"body_text\": \"Hi there, welcome to our service!\",\n \"created_at\": 1719474966,\n \"updated_at\": 1719493757,\n \"visible_to\": \"everyone\",\n \"visible_to_team_ids\": [],\n \"available_on\": [\"inbox\", \"messenger\"]\n }\n ],\n \"pages\": {\n \"type\": \"pages\",\n \"per_page\": 25,\n \"next\": {\n \"starting_after\": \"WzE3MTk0OTM3NTcuMCwgIjEyMyJd\"\n }\n }\n}" - } - ] - }, - { - "name": "List macros (with pagination)", - "tags": [ - "Macros" - ], - "request": { - "url": { - "raw": "https://api.intercom.io/macros?per_page=50&starting_after=WzE3MTk0OTM3NTcuMCwgIjEyMyJd", + "raw": "https://api.intercom.io/macros", "protocol": "https", "host": [ "api.intercom.io" @@ -5486,72 +5676,17 @@ { "key": "per_page", "value": "50", - "description": "Number of macros to return per page (max 150)" + "description": "The number of results per page" }, { "key": "starting_after", "value": "WzE3MTk0OTM3NTcuMCwgIjEyMyJd", - "description": "Cursor from previous response's pages.next.starting_after" - } - ], - "variable": [] - }, - "auth": { - "type": "bearer", - "bearer": [ - { - "key": "bearerToken", - "value": "{{bearerToken}}", - "type": "string" - }, - { - "key": "tokenType", - "value": "bearer", - "type": "string" + "description": "Base64-encoded cursor containing [updated_at, id] for pagination" }, - { - "key": "addTokenTo", - "value": "header", - "type": "string" - } - ] - }, - "method": "GET", - "description": "Demonstrates cursor-based pagination. Use the `starting_after` cursor from a previous response to retrieve the next page of results.\n\n**Important**: The cursor encodes `[updated_at, id]` to ensure stable ordering even as macros are modified.", - "header": [ - { - "key": "Intercom-Version", - "value": "Unstable" - }, - { - "key": "Accept", - "value": "application/json" - } - ], - "body": null - }, - "response": [] - }, - { - "name": "List macros (updated since)", - "tags": [ - "Macros" - ], - "request": { - "url": { - "raw": "https://api.intercom.io/macros?updated_since=1719474966", - "protocol": "https", - "host": [ - "api.intercom.io" - ], - "path": [ - "macros" - ], - "query": [ { "key": "updated_since", "value": "1719474966", - "description": "Unix timestamp - only return macros updated after this time" + "description": "Unix timestamp to filter macros updated after this time" } ], "variable": [] @@ -5577,7 +5712,7 @@ ] }, "method": "GET", - "description": "Efficiently sync recently modified macros by filtering with the `updated_since` parameter. Useful for:\n- Incremental synchronization with external systems\n- Tracking macro changes over time\n- Reducing API calls for large macro libraries", + "description": "You can fetch a list of all macros (saved replies) in your workspace for use in automating responses.\n\nThe macros are returned in descending order by updated_at. \n\n**Pagination**\n\nThis endpoint uses cursor-based pagination via the `starting_after` parameter. The cursor is a Base64-encoded JSON array containing `[updated_at, id]` of the last item from the previous page.\n\n**Placeholder Transformation**\n\nThe API transforms Intercom placeholders in the `body` field to a more standard XML-like format:\n- From: `{{user.name | fallback: 'there'}}`\n- To: ``\n\nNote: The `body_text` field retains the original Intercom placeholder format.\n", "header": [ { "key": "Intercom-Version", @@ -5593,38 +5728,30 @@ "response": [] }, { - "name": "List macros (complex example)", + "name": "Retrieve a macro", "tags": [ "Macros" ], "request": { "url": { - "raw": "https://api.intercom.io/macros?per_page=100&updated_since=1719474966&starting_after=WzE3MTk0OTM3NTcuMCwgIjQ1NiJd", + "raw": "https://api.intercom.io/macros/{id}", "protocol": "https", "host": [ "api.intercom.io" ], "path": [ - "macros" + "macros", + "{id}" ], - "query": [ - { - "key": "per_page", - "value": "100", - "description": "Retrieve up to 100 macros per request" - }, - { - "key": "updated_since", - "value": "1719474966", - "description": "Filter to macros updated after this timestamp" - }, + "query": [], + "variable": [ { - "key": "starting_after", - "value": "WzE3MTk0OTM3NTcuMCwgIjQ1NiJd", - "description": "Continue pagination from previous request" + "key": "id", + "value": "123", + "disabled": false, + "description": "The unique identifier of the macro" } - ], - "variable": [] + ] }, "auth": { "type": "bearer", @@ -5647,7 +5774,7 @@ ] }, "method": "GET", - "description": "Combines multiple parameters for advanced use cases:\n- Large batch retrieval (100 items)\n- Filtered by update time\n- With pagination continuation\n\nThis pattern is ideal for initial sync followed by incremental updates.", + "description": "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.\n\n**Visibility Rules**\n\nA macro is returned based on its `visible_to` setting:\n- `everyone`: Always visible to all team members\n- `specific_teams`: Only visible if the authenticated user belongs to one of the teams specified in `visible_to_team_ids`\n\nIf a macro exists but is not visible to the authenticated user, a 404 error is returned.\n\n**Placeholder Transformation**\n\nThe API transforms Intercom placeholders in the `body` field to a more standard XML-like format:\n- From: `{{user.name | fallback: 'there'}}`\n- To: ``\n\nNote: The `body_text` field retains the original Intercom placeholder format.\nDefault values in placeholders are HTML-escaped for security.\n", "header": [ { "key": "Intercom-Version", @@ -5661,32 +5788,47 @@ "body": null }, "response": [] - }, + } + ] + }, + { + "name": "Messages", + "item": [ { - "name": "Get a macro", + "name": "Get statuses of all messages sent based on the specified ruleset_id", "tags": [ - "Macros" + "Messages", + "WhatsApp" ], "request": { "url": { - "raw": "https://api.intercom.io/macros/:id", + "raw": "https://api.intercom.io/messages/status", "protocol": "https", "host": [ "api.intercom.io" ], "path": [ - "macros", - ":id" - ], - "query": [], - "variable": [ + "messages", + "status" + ], + "query": [ { - "key": "id", - "value": "123", - "disabled": false, - "description": "The ID of the macro to retrieve" + "key": "ruleset_id", + "value": "ruleset_id", + "description": "The unique identifier for the set of messages to check status for" + }, + { + "key": "per_page", + "value": "per_page", + "description": "Number of results per page (default 50, max 100)" + }, + { + "key": "starting_after", + "value": "starting_after", + "description": "Cursor for pagination, used to fetch the next page of results" } - ] + ], + "variable": [] }, "auth": { "type": "bearer", @@ -5709,7 +5851,7 @@ ] }, "method": "GET", - "description": "Retrieves a single macro by its ID. Use this endpoint when you need:\n- Full details of a specific macro\n- To verify a macro still exists\n- To check for updates to a known macro\n\n**Note**: Returns 404 if the macro doesn't exist or isn't visible to the authenticated user.", + "description": "Retrieves statuses of messages sent from the Outbound module. Currently, this API only supports WhatsApp messages.\n\n\nThis endpoint returns paginated status events for WhatsApp messages sent via the Outbound module, providing\ninformation about delivery state and related message details.\n", "header": [ { "key": "Intercom-Version", @@ -5722,82 +5864,8 @@ ], "body": null }, - "response": [ - { - "name": "Successful response", - "status": "OK", - "code": 200, - "_postman_previewlanguage": "json", - "header": [], - "cookie": [], - "body": "{\n \"type\": \"macro\",\n \"id\": \"123\",\n \"name\": \"Order Confirmation\",\n \"body\": \"

Thank you for your order, !

Order # has been confirmed.

\",\n \"body_text\": \"Thank you for your order, valued customer!\\n\\nOrder # has been confirmed.\",\n \"created_at\": 1719474966,\n \"updated_at\": 1719493757,\n \"visible_to\": \"selected_teams\",\n \"visible_to_team_ids\": [456, 789],\n \"available_on\": [\"inbox\"]\n}" - }, - { - "name": "Not found", - "status": "Not Found", - "code": 404, - "_postman_previewlanguage": "json", - "header": [], - "cookie": [], - "body": "{\n \"type\": \"error.list\",\n \"errors\": [\n {\n \"code\": \"not_found\",\n \"message\": \"Macro not found\"\n }\n ]\n}" - } - ] - } - ], - "event": [ - { - "listen": "prerequest", - "script": { - "type": "text/javascript", - "exec": [ - "// Ensure Intercom-Version header is set for Unstable API", - "pm.request.headers.add({", - " key: 'Intercom-Version',", - " value: 'Unstable'", - "});" - ] - } + "response": [] }, - { - "listen": "test", - "script": { - "type": "text/javascript", - "exec": [ - "// Example test for List all macros", - "pm.test(\"Status code is 200\", function () {", - " pm.response.to.have.status(200);", - "});", - "", - "pm.test(\"Response has correct structure\", function () {", - " var jsonData = pm.response.json();", - " pm.expect(jsonData).to.have.property('type', 'list');", - " pm.expect(jsonData).to.have.property('data');", - " pm.expect(jsonData).to.have.property('pages');", - "});", - "", - "pm.test(\"Macros have transformed placeholders\", function () {", - " var jsonData = pm.response.json();", - " if (jsonData.data && jsonData.data.length > 0) {", - " var macro = jsonData.data[0];", - " if (macro.body && macro.body.includes('{{')) {", - " pm.expect(macro.body).to.include(' 🚧 Sending for visitors\n>\n> There can be a short delay between when a contact is created and when a contact becomes available to be messaged through the API. A 404 Not Found error will be returned in this case.\n\nThis will return the Message model that has been created.\n\n> 🚧 Retrieving Associated Conversations\n>\n> As this is a message, there will be no conversation present until the contact responds. Once they do, you will have to search for a contact's conversations with the id of the message.\n", "header": [ { "key": "Intercom-Version", @@ -5854,7 +5922,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"message_type\": \"in_app\",\n \"subject\": \"Thanks for everything\",\n \"body\": \"Hello there\",\n \"template\": \"plain\",\n \"from\": {\n \"type\": \"admin\",\n \"id\": 394051\n },\n \"to\": {\n \"type\": \"user\",\n \"id\": \"536e564f316c83104c000020\"\n },\n \"created_at\": 1590000000,\n \"create_conversation_without_contact_reply\": true\n}", + "raw": "{\n \"message_type\": \"in_app\",\n \"subject\": \"Thanks for everything\",\n \"body\": \"Hello there\",\n \"template\": \"plain\",\n \"from\": {\n \"type\": \"admin\",\n \"id\": 394051\n },\n \"to\": [\n {\n \"type\": \"user\",\n \"id\": \"536e564f316c83104c000020\"\n },\n {\n \"type\": \"lead\",\n \"id\": \"536e564f316c83104c000021\"\n }\n ],\n \"cc\": [\n {\n \"type\": \"user\",\n \"id\": \"536e564f316c83104c000023\"\n }\n ],\n \"bcc\": [\n {\n \"type\": \"user\",\n \"id\": \"536e564f316c83104c000022\"\n }\n ],\n \"created_at\": 1590000000,\n \"create_conversation_without_contact_reply\": true\n}", "urlencoded": [], "formdata": [] } @@ -8384,7 +8452,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"message_type\": \"comment\",\n \"type\": \"admin\",\n \"body\": \"Hello there!\",\n \"created_at\": 1590000000,\n \"attachment_urls\": \"\",\n \"admin_id\": \"3156780\",\n \"reply_options\": [\n {\n \"text\": \"\",\n \"uuid\": \"\"\n }\n ]\n}", + "raw": "{\n \"message_type\": \"comment\",\n \"type\": \"admin\",\n \"body\": \"Hello there!\",\n \"created_at\": 1590000000,\n \"attachment_urls\": \"\",\n \"reply_options\": [\n {\n \"text\": \"\",\n \"uuid\": \"\"\n }\n ],\n \"admin_id\": \"3156780\"\n}", "urlencoded": [], "formdata": [] } @@ -8558,7 +8626,7 @@ ] }, "method": "POST", - "description": "You can search for multiple tickets by the value of their attributes in order to fetch exactly which ones you want.\n\nTo search for tickets, you send a `POST` request to `https://api.intercom.io/tickets/search`.\n\nThis will accept a query object in the body which will define your filters.\n{% admonition type=\"warning\" name=\"Optimizing search queries\" %}\n Search queries can be complex, so optimizing them can help the performance of your search.\n Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize\n pagination to limit the number of results returned. The default is `20` results per page.\n See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.\n{% /admonition %}\n\n### Nesting & Limitations\n\nYou can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4).\nThere are some limitations to the amount of multiples there can be:\n- There's a limit of max 2 nested filters\n- There's a limit of max 15 filters for each AND or OR group\n\n### Accepted Fields\n\nMost keys listed as part of the Ticket model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `\"foobar\"`).\nThe `source.body` field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a `\"I need support\"` body - the query should contain a `=` operator with the value `\"support\"` for such conversation to be returned. A query with a `=` operator and a `\"need support\"` value will not yield a result.\n\n| Field | Type |\n| :---------------------------------------- | :--------------------------------------------------------------------------------------- |\n| id | String |\n| created_at | Date (UNIX timestamp) |\n| updated_at | Date (UNIX timestamp) |\n| _default_title_ | String |\n| _default_description_ | String |\n| category | String |\n| ticket_type_id | String |\n| contact_ids | String |\n| teammate_ids | String |\n| admin_assignee_id | String |\n| team_assignee_id | String |\n| open | Boolean |\n| state | String |\n| snoozed_until | Date (UNIX timestamp) |\n| ticket_attribute.{id} | String or Boolean or Date (UNIX timestamp) or Float or Integer |\n\n### Accepted Operators\n\n{% admonition type=\"info\" name=\"Searching based on `created_at`\" %}\n You may use the `<=` or `>=` operators to search by `created_at`.\n{% /admonition %}\n\nThe table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`\"=\"`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates).\n\n| Operator | Valid Types | Description |\n| :------- | :----------------------------- | :----------------------------------------------------------- |\n| = | All | Equals |\n| != | All | Doesn't Equal |\n| IN | All | In Shortcut for `OR` queries Values most be in Array |\n| NIN | All | Not In Shortcut for `OR !` queries Values must be in Array |\n| > | Integer Date (UNIX Timestamp) | Greater (or equal) than |\n| < | Integer Date (UNIX Timestamp) | Lower (or equal) than |\n| ~ | String | Contains |\n| !~ | String | Doesn't Contain |\n| ^ | String | Starts With |\n| $ | String | Ends With |\n", + "description": "You can search for multiple tickets by the value of their attributes in order to fetch exactly which ones you want.\n\nTo search for tickets, you send a `POST` request to `https://api.intercom.io/tickets/search`.\n\nThis will accept a query object in the body which will define your filters.\n{% admonition type=\"warning\" name=\"Optimizing search queries\" %}\n Search queries can be complex, so optimizing them can help the performance of your search.\n Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize\n pagination to limit the number of results returned. The default is `20` results per page.\n See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.\n{% /admonition %}\n\n### Nesting & Limitations\n\nYou can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4).\nThere are some limitations to the amount of multiples there can be:\n- There's a limit of max 2 nested filters\n- There's a limit of max 15 filters for each AND or OR group\n\n### Accepted Fields\n\nMost keys listed as part of the Ticket model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `\"foobar\"`).\nThe `source.body` field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a `\"I need support\"` body - the query should contain a `=` operator with the value `\"support\"` for such conversation to be returned. A query with a `=` operator and a `\"need support\"` value will not yield a result.\n\n| Field | Type |\n| :---------------------------------------- | :--------------------------------------------------------------------------------------- |\n| id | String |\n| created_at | Date (UNIX timestamp) |\n| updated_at | Date (UNIX timestamp) |\n| _default_title_ | String |\n| _default_description_ | String |\n| category | String |\n| ticket_type_id | String |\n| contact_ids | String |\n| teammate_ids | String |\n| admin_assignee_id | String |\n| team_assignee_id | String |\n| open | Boolean |\n| state | String |\n| snoozed_until | Date (UNIX timestamp) |\n| ticket_attribute.{id} | String or Boolean or Date (UNIX timestamp) or Float or Integer |\n\n{% admonition type=\"info\" name=\"Searching by Category\" %}\nWhen searching for tickets by the **`category`** field, specific terms must be used instead of the category names:\n* For **Customer** category tickets, use the term `request`.\n* For **Back-office** category tickets, use the term `task`.\n* For **Tracker** category tickets, use the term `tracker`.\n{% /admonition %}\n\n### Accepted Operators\n\n{% admonition type=\"info\" name=\"Searching based on `created_at`\" %}\n You may use the `<=` or `>=` operators to search by `created_at`.\n{% /admonition %}\n\nThe table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`\"=\"`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates).\n\n| Operator | Valid Types | Description |\n| :------- | :----------------------------- | :----------------------------------------------------------- |\n| = | All | Equals |\n| != | All | Doesn't Equal |\n| IN | All | In Shortcut for `OR` queries Values most be in Array |\n| NIN | All | Not In Shortcut for `OR !` queries Values must be in Array |\n| > | Integer Date (UNIX Timestamp) | Greater (or equal) than |\n| < | Integer Date (UNIX Timestamp) | Lower (or equal) than |\n| ~ | String | Contains |\n| !~ | String | Doesn't Contain |\n| ^ | String | Starts With |\n| $ | String | Ends With |\n", "header": [ { "key": "Intercom-Version", @@ -8908,12 +8976,270 @@ "response": [] } ] + }, + { + "name": "Export", + "item": [ + { + "name": "Get export job status", + "tags": [ + "Export" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/export/reporting_data/{job_identifier}", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "export", + "reporting_data", + "{job_identifier}" + ], + "query": [ + { + "key": "app_id", + "value": "app_id", + "description": "The Intercom defined code of the workspace the company is associated to." + }, + { + "key": "client_id", + "value": "client_id" + }, + { + "key": "job_identifier", + "value": "job_identifier", + "description": "Unique identifier of the job." + } + ], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "GET", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + }, + { + "name": "List available datasets and attributes", + "tags": [ + "Export" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/export/reporting_data/get_datasets", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "export", + "reporting_data", + "get_datasets" + ], + "query": [], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "GET", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + }, + { + "name": "Download completed export job data", + "tags": [ + "Export" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/download/reporting_data/{job_identifier}", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "download", + "reporting_data", + "{job_identifier}" + ], + "query": [ + { + "key": "app_id", + "value": "app_id" + }, + { + "key": "job_identifier", + "value": "job_identifier" + } + ], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "GET", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + }, + { + "name": "Enqueue a new reporting data export job", + "tags": [ + "Export" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/export/reporting_data/enqueue", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "export", + "reporting_data", + "enqueue" + ], + "query": [], + "variable": [] + }, + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "bearerToken", + "value": "{{bearerToken}}", + "type": "string" + }, + { + "key": "tokenType", + "value": "bearer", + "type": "string" + }, + { + "key": "addTokenTo", + "value": "header", + "type": "string" + } + ] + }, + "method": "POST", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"dataset_id\": \"conversation\",\n \"attribute_ids\": [\n \"conversation.id\",\n \"conversation.first_user_conversation_part_created_at\"\n ],\n \"start_time\": 1717490000,\n \"end_time\": 1717510000\n}", + "urlencoded": [], + "formdata": [] + } + }, + "response": [] + } + ] } ], "event": [], "variable": [ { - "id": "0b660c74-42c3-4abf-a3f8-93b932218d3f", + "id": "cc12d50b-b03e-47fa-aed5-b5a257f37bfb", "key": "bearerToken", "value": "{{bearerToken}}", "type": "string", From c47c7fe7b4f2539f27cf35ccbabefe8b93286e2c Mon Sep 17 00:00:00 2001 From: Levin Dixon Date: Thu, 31 Jul 2025 11:37:04 +0100 Subject: [PATCH 7/8] docs(api): Add code samples and comprehensive examples to Macros API endpoints (intercom/intercom#420117) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add code samples in cURL, Node.js, Python, and Ruby for both endpoints - Expand response examples with multiple scenarios including pagination, filtering, and various macro types - Improve error response examples with clearer messaging - Fix tags from 'Unstable' to 'Macros' for proper categorization - Enhance tag description for better API documentation navigation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 302 ++++++++++++++++++++++++---- 1 file changed, 266 insertions(+), 36 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 16e2aa1..59e8c13 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -9255,36 +9255,201 @@ paths: **Placeholder Transformation** - The API transforms Intercom placeholders in the `body` field to a more standard XML-like format: + The API transforms Intercom placeholders to a more standard XML-like format: - From: `{{user.name | fallback: 'there'}}` - To: `` - - Note: The `body_text` field retains the original Intercom placeholder format. + x-code-samples: + - lang: 'cURL' + source: | + curl -X GET 'https://api.intercom.io/macros?per_page=25&starting_after=WzE3MTk0OTM3NTcuMCwgIjEyMyJd' \ + -H 'Authorization: Bearer ' \ + -H 'Accept: application/json' \ + -H 'Intercom-Version: @Unstable' + - lang: 'Node.js' + source: | + const response = await fetch('https://api.intercom.io/macros?per_page=25&starting_after=WzE3MTk0OTM3NTcuMCwgIjEyMyJd', { + headers: { + 'Authorization': 'Bearer ', + 'Accept': 'application/json', + 'Intercom-Version': '@Unstable' + } + }); + const macros = await response.json(); + - lang: 'Python' + source: | + import requests + + headers = { + 'Authorization': 'Bearer ', + 'Accept': 'application/json', + 'Intercom-Version': '@Unstable' + } + + params = { + 'per_page': 25, + 'starting_after': 'WzE3MTk0OTM3NTcuMCwgIjEyMyJd' + } + + response = requests.get('https://api.intercom.io/macros', + headers=headers, + params=params) + macros = response.json() + - lang: 'Ruby' + source: | + require 'net/http' + require 'json' + + uri = URI('https://api.intercom.io/macros') + params = { + per_page: 25, + starting_after: 'WzE3MTk0OTM3NTcuMCwgIjEyMyJd' + } + uri.query = URI.encode_www_form(params) + + http = Net::HTTP.new(uri.host, uri.port) + http.use_ssl = true + + request = Net::HTTP::Get.new(uri) + request['Authorization'] = 'Bearer ' + request['Accept'] = 'application/json' + request['Intercom-Version'] = '@Unstable' + + response = http.request(request) + macros = JSON.parse(response.body) responses: '200': description: Successful response content: application/json: examples: - Successful response: + basic_list: + summary: Basic list of macros value: type: list data: - type: macro id: "123" name: "Order Status Update" - body: "

Hi , your order # is ready!

" - body_text: "Hi {{user.name|fallback:\"there\"}}, your order is ready!" + body: "

Hi , your order # is ready for pickup!

" + body_text: "Hi {{user.name|fallback:\"there\"}}, your order #{{order.number}} is ready for pickup!" created_at: "2025-07-17T11:18:08.000Z" updated_at: "2025-07-17T15:30:24.000Z" visible_to: "everyone" visible_to_team_ids: [] available_on: ["inbox", "messenger"] + - type: macro + id: "456" + name: "Welcome Message" + body: "

Welcome to our support! I'm . How can I help you today?

" + body_text: "Welcome to our support! I'm {{teammate.name}}. How can I help you today?" + created_at: "2025-07-21T14:44:35.000Z" + updated_at: "2025-07-21T14:44:35.000Z" + visible_to: "specific_teams" + visible_to_team_ids: ["789", "101"] + available_on: ["inbox"] pages: type: pages per_page: 50 next: starting_after: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd" + pagination_with_cursor: + summary: Paginated response using starting_after cursor + value: + type: list + data: + - type: macro + id: "789" + name: "Refund Process" + body: "

I understand you'd like a refund for order #. The refund will be processed within 3-5 business days.

" + body_text: "I understand you'd like a refund for order #{{conversation.custom_attributes.order_number}}. The refund will be processed within 3-5 business days." + created_at: "2025-07-21T07:15:34.000Z" + updated_at: "2025-07-21T07:15:34.000Z" + visible_to: "everyone" + visible_to_team_ids: [] + available_on: ["inbox", "messenger"] + - type: macro + id: "101" + name: "Product Inquiry Response" + body: "

Thank you for your interest in . I'd be happy to provide more information!

" + body_text: "Thank you for your interest in {{product.name|fallback:\"our products\"}}. I'd be happy to provide more information!" + created_at: "2025-07-20T05:33:20.000Z" + updated_at: "2025-07-21T10:00:00.000Z" + visible_to: "everyone" + visible_to_team_ids: [] + available_on: ["inbox", "messenger"] + pages: + type: pages + per_page: 50 + next: + starting_after: "WzE3MTk0MDAwMDAuMCwgIjEwMSJd" + filtered_by_timestamp: + summary: Macros filtered by updated_since parameter + value: + type: list + data: + - type: macro + id: "234" + name: "Shipping Update Template" + body: "

Your order has been shipped via . Tracking number:

" + body_text: "Your order has been shipped via {{shipping.carrier|fallback:\"our shipping partner\"}}. Tracking number: {{shipping.tracking_number}}" + created_at: "2025-07-22T05:31:01.000Z" + updated_at: "2025-07-22T18:45:12.000Z" + visible_to: "everyone" + visible_to_team_ids: [] + available_on: ["inbox"] + pages: + type: pages + per_page: 50 + next: null + complex_placeholders: + summary: Macros with various placeholder formats + value: + type: list + data: + - type: macro + id: "567" + name: "Account Status Review" + body: "

Hi ,

Your account status:

Last activity:

" + body_text: "Hi {{user.first_name|fallback:\"there\"}},\n\nYour account status: {{user.custom_attributes.account_status|fallback:\"pending review\"}}\n\nLast activity: {{user.last_seen_at}}" + created_at: "2025-07-21T09:00:00.000Z" + updated_at: "2025-07-21T09:00:00.000Z" + visible_to: "specific_teams" + visible_to_team_ids: ["security_team"] + available_on: ["inbox"] + pages: + type: pages + per_page: 50 + next: null + empty_result: + summary: Empty macro list (no macros or all filtered out) + value: + type: list + data: [] + pages: + type: pages + per_page: 50 + next: null + large_list_preview: + summary: Large list with performance optimization + value: + type: list + data: + - type: macro + id: "1001" + name: "Quick Response 1" + body: null + body_text: null + created_at: "2025-07-22T11:08:20.000Z" + updated_at: "2025-07-23T11:08:20.000Z" + visible_to: "everyone" + visible_to_team_ids: [] + available_on: ["inbox"] + # Note: When returning 30+ macros, body rendering may be skipped for performance + pages: + type: pages + per_page: 50 + next: + starting_after: "WzE3MTk0OTAxMDAuMCwgIjEwMDIiXQ==" schema: "$ref": "#/components/schemas/macro_list" '400': @@ -9320,13 +9485,14 @@ paths: content: application/json: examples: - Missing scope: + Missing required scope: + summary: OAuth token lacks read_conversations scope value: type: error.list request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef errors: - code: forbidden - message: Token does not have the required 'read_conversations' scope + message: You do not have the required scope (read_conversations) to access this resource schema: "$ref": "#/components/schemas/error" "/macros/{id}": @@ -9360,49 +9526,111 @@ paths: **Placeholder Transformation** - The API transforms Intercom placeholders in the `body` field to a more standard XML-like format: + The API transforms Intercom placeholders to a more standard XML-like format in the `body` field: - From: `{{user.name | fallback: 'there'}}` - To: `` - Note: The `body_text` field retains the original Intercom placeholder format. Default values in placeholders are HTML-escaped for security. + x-code-samples: + - lang: 'cURL' + source: | + curl -X GET 'https://api.intercom.io/macros/123' \ + -H 'Authorization: Bearer ' \ + -H 'Accept: application/json' \ + -H 'Intercom-Version: @Unstable' + - lang: 'Node.js' + source: | + const response = await fetch('https://api.intercom.io/macros/123', { + headers: { + 'Authorization': 'Bearer ', + 'Accept': 'application/json', + 'Intercom-Version': '@Unstable' + } + }); + const macro = await response.json(); + - lang: 'Python' + source: | + import requests + + headers = { + 'Authorization': 'Bearer ', + 'Accept': 'application/json', + 'Intercom-Version': '@Unstable' + } + + response = requests.get('https://api.intercom.io/macros/123', + headers=headers) + macro = response.json() + - lang: 'Ruby' + source: | + require 'net/http' + require 'json' + + uri = URI('https://api.intercom.io/macros/123') + + http = Net::HTTP.new(uri.host, uri.port) + http.use_ssl = true + + request = Net::HTTP::Get.new(uri) + request['Authorization'] = 'Bearer ' + request['Accept'] = 'application/json' + request['Intercom-Version'] = '@Unstable' + + response = http.request(request) + macro = JSON.parse(response.body) responses: '200': description: Macro found content: application/json: examples: - Macro visible to everyone: + support_macro: + summary: Customer support macro with placeholders value: type: macro - id: "123" - name: "Order Status Update" - body: "

Hi , your order # is ready for pickup!

" - body_text: "Hi {{user.name|fallback:\"there\"}}, your order is ready for pickup!" - created_at: "2025-07-17T11:18:08.000Z" - updated_at: "2025-07-17T15:30:24.000Z" - visible_to: "everyone" - visible_to_team_ids: [] + id: "789" + name: "Refund Process Explanation" + body: "

Hi ,

I understand you'd like a refund for order #. The refund will be processed within 3-5 business days to your .

Is there anything else I can help you with?

" + 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"] - Macro with team restrictions: + sales_macro: + summary: Sales team macro for product inquiries value: type: macro id: "456" - name: "VIP Customer Support" - body: "

Dear , we appreciate your VIP status. Your dedicated support team is here to help.

" - body_text: "Dear {{user.name|fallback:\"valued customer\"}}, we appreciate your VIP status. Your dedicated support team is here to help." - created_at: "2025-07-17T11:18:08.000Z" - updated_at: "2025-07-17T15:30:24.000Z" + name: "Product Demo Request" + body: "

Hello ,

Thank you for your interest in ! I'd love to schedule a personalized demo for your team at .

Would work for you?

" + body_text: "Hello {{user.name|fallback:\"valued customer\"}},\n\nThank you for your interest in {{product.name|fallback:\"our products\"}}! I'd love to schedule a personalized demo for your team at {{company.name|fallback:\"your company\"}}.\n\nWould {{suggested_time|fallback:\"next Tuesday at 2 PM EST\"}} work for you?" + created_at: "2025-07-22T11:06:40.000Z" + updated_at: "2025-07-23T00:00:00.000Z" visible_to: "specific_teams" - visible_to_team_ids: ["789", "012"] + visible_to_team_ids: ["sales_team_us", "sales_team_eu"] + available_on: ["messenger"] + technical_support: + summary: Technical support macro with nested attributes + value: + type: macro + id: "890" + name: "API Integration Help" + body: "

Hi ,

I see you're having trouble with the integration. Your API key for app is configured correctly.

Error code:

Let me help you resolve this issue.

" + body_text: "Hi {{user.name}},\n\nI see you're having trouble with the {{conversation.custom_attributes.api_endpoint|fallback:\"API\"}} integration. Your API key for app {{app.id}} is configured correctly.\n\nError code: {{conversation.custom_attributes.error_code|fallback:\"unknown\"}}\n\nLet me help you resolve this issue." + created_at: "2025-07-18T09:15:00.000Z" + updated_at: "2025-07-18T09:15:00.000Z" + visible_to: "everyone" + visible_to_team_ids: [] available_on: ["inbox"] - Macro with complex placeholders: + simple_greeting: + summary: Simple macro without placeholders value: type: macro - id: "789" - name: "Account Summary" - body: "

Hello !

Your account balance is .

Last login:

" - body_text: "Hello {{user.name|fallback:\"there\"}}! Your account balance is {{account.balance|fallback:\"not available\"}}. Last login: {{user.last_login|fallback:\"never\"}}" + id: "123" + name: "Thank You Response" + body: "

Thank you for reaching out! We appreciate your message and will get back to you as soon as possible.

" + body_text: "Thank you for reaching out! We appreciate your message and will get back to you as soon as possible." created_at: "2025-07-17T11:18:08.000Z" updated_at: "2025-07-17T15:30:24.000Z" visible_to: "everyone" @@ -9429,13 +9657,14 @@ paths: content: application/json: examples: - Missing scope: + Missing required scope: + summary: OAuth token lacks read_conversations scope value: type: error.list request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef errors: - code: forbidden - message: Token does not have the required 'read_conversations' scope + message: You do not have the required scope (read_conversations) to access this resource schema: "$ref": "#/components/schemas/error" '404': @@ -18947,7 +19176,7 @@ components: title: Macro type: object x-tags: - - Unstable + - Macros description: A macro is a pre-defined response template (saved reply) that can be used to quickly reply to conversations. nullable: true properties: @@ -19020,7 +19249,7 @@ components: title: Macro List type: object x-tags: - - Unstable + - Macros description: A paginated list of macros (saved replies) in the workspace. properties: type: @@ -21770,7 +21999,8 @@ tags: - name: Jobs description: Everything about jobs - name: Macros - description: Everything about your Macros (Saved Replies) + description: Operations related to saved replies (macros) in conversations + x-displayName: Macros - name: Messages description: Everything about your messages - name: News From 17c0cd7e77809db5cf8bc443e9655e7dc7597992 Mon Sep 17 00:00:00 2001 From: Levin Dixon Date: Thu, 31 Jul 2025 14:58:40 +0100 Subject: [PATCH 8/8] fix(api): Remove incorrect required field constraints from Macros API schemas (intercom/intercom#420117) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove overly restrictive required field definitions from macro and macro_list schemas - Update Postman collection timestamps - Simplify placeholder transformation descriptions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 20 ------------------- postman/Unstable/README.md | 2 +- .../intercom-api.postman_collection.json | 8 ++++---- 3 files changed, 5 insertions(+), 25 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 59e8c13..9207c2a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -19234,17 +19234,6 @@ components: - inbox - messenger example: ["inbox", "messenger"] - required: - - type - - id - - name - - body - - body_text - - created_at - - updated_at - - visible_to - - visible_to_team_ids - - available_on macro_list: title: Macro List type: object @@ -19286,15 +19275,6 @@ components: type: string description: Base64-encoded cursor containing [updated_at, id] for pagination example: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd" - required: - - starting_after - required: - - type - - per_page - required: - - type - - data - - pages merge_contacts_request: description: Merge contact data. type: object diff --git a/postman/Unstable/README.md b/postman/Unstable/README.md index 657d53c..fe41e05 100644 --- a/postman/Unstable/README.md +++ b/postman/Unstable/README.md @@ -12,4 +12,4 @@ This directory contains the Postman collection for Intercom API version Unstable 3. Set your access token in the environment variables 4. Start making API calls! -Last updated: 2025-07-31T07:41:44.918Z +Last updated: 2025-07-31T13:47:07.414Z diff --git a/postman/Unstable/intercom-api.postman_collection.json b/postman/Unstable/intercom-api.postman_collection.json index 4da4790..170fe6b 100644 --- a/postman/Unstable/intercom-api.postman_collection.json +++ b/postman/Unstable/intercom-api.postman_collection.json @@ -8,7 +8,7 @@ "url": "https://developers.intercom.com" }, "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", - "updatedAt": "2025-07-31T07:41:44.914Z" + "updatedAt": "2025-07-31T13:47:07.412Z" }, "item": [ { @@ -5712,7 +5712,7 @@ ] }, "method": "GET", - "description": "You can fetch a list of all macros (saved replies) in your workspace for use in automating responses.\n\nThe macros are returned in descending order by updated_at. \n\n**Pagination**\n\nThis endpoint uses cursor-based pagination via the `starting_after` parameter. The cursor is a Base64-encoded JSON array containing `[updated_at, id]` of the last item from the previous page.\n\n**Placeholder Transformation**\n\nThe API transforms Intercom placeholders in the `body` field to a more standard XML-like format:\n- From: `{{user.name | fallback: 'there'}}`\n- To: ``\n\nNote: The `body_text` field retains the original Intercom placeholder format.\n", + "description": "You can fetch a list of all macros (saved replies) in your workspace for use in automating responses.\n\nThe macros are returned in descending order by updated_at. \n\n**Pagination**\n\nThis endpoint uses cursor-based pagination via the `starting_after` parameter. The cursor is a Base64-encoded JSON array containing `[updated_at, id]` of the last item from the previous page.\n\n**Placeholder Transformation**\n\nThe API transforms Intercom placeholders to a more standard XML-like format:\n- From: `{{user.name | fallback: 'there'}}`\n- To: ``\n", "header": [ { "key": "Intercom-Version", @@ -5774,7 +5774,7 @@ ] }, "method": "GET", - "description": "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.\n\n**Visibility Rules**\n\nA macro is returned based on its `visible_to` setting:\n- `everyone`: Always visible to all team members\n- `specific_teams`: Only visible if the authenticated user belongs to one of the teams specified in `visible_to_team_ids`\n\nIf a macro exists but is not visible to the authenticated user, a 404 error is returned.\n\n**Placeholder Transformation**\n\nThe API transforms Intercom placeholders in the `body` field to a more standard XML-like format:\n- From: `{{user.name | fallback: 'there'}}`\n- To: ``\n\nNote: The `body_text` field retains the original Intercom placeholder format.\nDefault values in placeholders are HTML-escaped for security.\n", + "description": "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.\n\n**Visibility Rules**\n\nA macro is returned based on its `visible_to` setting:\n- `everyone`: Always visible to all team members\n- `specific_teams`: Only visible if the authenticated user belongs to one of the teams specified in `visible_to_team_ids`\n\nIf a macro exists but is not visible to the authenticated user, a 404 error is returned.\n\n**Placeholder Transformation**\n\nThe API transforms Intercom placeholders to a more standard XML-like format in the `body` field:\n- From: `{{user.name | fallback: 'there'}}`\n- To: ``\n\nDefault values in placeholders are HTML-escaped for security.\n", "header": [ { "key": "Intercom-Version", @@ -9239,7 +9239,7 @@ "event": [], "variable": [ { - "id": "cc12d50b-b03e-47fa-aed5-b5a257f37bfb", + "id": "02513ace-fee8-491d-a182-ea7bdcdff035", "key": "bearerToken", "value": "{{bearerToken}}", "type": "string",