diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f90b489..9207c2a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -9211,6 +9211,476 @@ 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: `` + 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: + 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 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': + 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 required scope: + summary: OAuth token lacks read_conversations scope + value: + type: error.list + request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef + errors: + - code: forbidden + message: You do not have the required scope (read_conversations) to access this resource + 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 unique identifier of the macro + schema: + type: string + example: "123" + tags: + - Macros + operationId: getMacro + 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. + + **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: `` + + 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: + support_macro: + summary: Customer support macro with placeholders + value: + type: macro + 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"] + sales_macro: + summary: Sales team macro for product inquiries + value: + type: macro + id: "456" + 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: ["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"] + simple_greeting: + summary: Simple macro without placeholders + value: + type: macro + 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" + visible_to_team_ids: [] + available_on: ["inbox", "messenger"] + schema: + "$ref": "#/components/schemas/macro" + '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 required scope: + summary: OAuth token lacks read_conversations scope + value: + type: error.list + request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef + errors: + - code: forbidden + message: You do not have the required scope (read_conversations) to access this resource + 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 @@ -18702,6 +19172,109 @@ components: description: An array containing the linked conversations and linked tickets. items: "$ref": "#/components/schemas/linked_object" + macro: + title: Macro + type: object + x-tags: + - Macros + 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 with original Intercom placeholder format. + example: "Hi {{user.name|fallback:\"there\"}}, your order is ready!" + created_at: + 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: 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. + 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"] + macro_list: + title: Macro List + type: object + x-tags: + - Macros + 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" merge_contacts_request: description: Merge contact data. type: object @@ -21405,6 +21978,9 @@ tags: description: Everything about your Help Center - name: Jobs description: Everything about jobs +- name: Macros + description: Operations related to saved replies (macros) in conversations + x-displayName: Macros - name: Messages description: Everything about your messages - name: News diff --git a/postman/Unstable/README.md b/postman/Unstable/README.md index 49b48d5..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-04-25T10:49:24.297Z +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 58a8b4a..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-04-25T10:49:24.294Z" + "updatedAt": "2025-07-31T13:47:07.412Z" }, "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": [ @@ -5345,15 +5606,229 @@ "status", "{id}" ], - "query": [], - "variable": [ + "query": [], + "variable": [ + { + "key": "id", + "value": "id", + "disabled": false, + "description": "The unique identifier for the job which is given by Intercom" + } + ] + }, + "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": "Retrieve the status of job execution.", + "header": [ + { + "key": "Intercom-Version", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + } + ] + }, + { + "name": "Macros", + "item": [ + { + "name": "List all macros", + "tags": [ + "Macros" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/macros", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "macros" + ], + "query": [ + { + "key": "per_page", + "value": "50", + "description": "The number of results per page" + }, + { + "key": "starting_after", + "value": "WzE3MTk0OTM3NTcuMCwgIjEyMyJd", + "description": "Base64-encoded cursor containing [updated_at, id] for pagination" + }, + { + "key": "updated_since", + "value": "1719474966", + "description": "Unix timestamp to filter 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": "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", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + }, + { + "name": "Retrieve 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 unique identifier of the macro" + } + ] + }, + "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": "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", + "value": "Unstable" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": null + }, + "response": [] + } + ] + }, + { + "name": "Messages", + "item": [ + { + "name": "Get statuses of all messages sent based on the specified ruleset_id", + "tags": [ + "Messages", + "WhatsApp" + ], + "request": { + "url": { + "raw": "https://api.intercom.io/messages/status", + "protocol": "https", + "host": [ + "api.intercom.io" + ], + "path": [ + "messages", + "status" + ], + "query": [ { - "key": "id", - "value": "id", - "disabled": false, - "description": "The unique identifier for the job which is given by Intercom" + "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", @@ -5376,7 +5851,7 @@ ] }, "method": "GET", - "description": "Retrieve the status of job execution.", + "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", @@ -5390,12 +5865,7 @@ "body": null }, "response": [] - } - ] - }, - { - "name": "Messages", - "item": [ + }, { "name": "Create a message", "tags": [ @@ -5435,7 +5905,7 @@ ] }, "method": "POST", - "description": "You can create a message that has been initiated by an admin. The conversation can be either an in-app message, an email or sms.\n\n> 🚧 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", + "description": "You can create a message that has been initiated by an admin. The conversation can be either an in-app message, an email, sms or whatsapp.\n\n> 🚧 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", @@ -5452,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": [] } @@ -7982,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": [] } @@ -8156,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", @@ -8506,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": "02513ace-fee8-491d-a182-ea7bdcdff035", "key": "bearerToken", "value": "{{bearerToken}}", "type": "string",