{"templateId":"markdown","versions":[{"version":"1.0","label":"v1.0","link":"/docs/references/1.0/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"1.1","label":"v1.1","link":"/docs/references/1.1/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"1.2","label":"v1.2","link":"/docs/references/1.2/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"1.3","label":"v1.3","link":"/docs/references/1.3/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"1.4","label":"v1.4","link":"/docs/references/1.4/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.0","label":"v2.0","link":"/docs/references/2.0/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.1","label":"v2.1","link":"/docs/references/2.1/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.2","label":"v2.2","link":"/docs/references/2.2/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.3","label":"v2.3","link":"/docs/references/2.3/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.4","label":"v2.4","link":"/docs/references/2.4/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.5","label":"v2.5","link":"/docs/references/2.5/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.6","label":"v2.6","link":"/docs/references/2.6/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.7","label":"v2.7","link":"/docs/references/2.7/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.8","label":"v2.8","link":"/docs/references/2.8/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.9","label":"v2.9","link":"/docs/references/2.9/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.10","label":"v2.10","link":"/docs/references/2.10/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.11","label":"v2.11","link":"/docs/references/2.11/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.12","label":"v2.12","link":"/docs/references/2.12/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.13","label":"v2.13","link":"/docs/references/2.13/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.14","label":"v2.14","link":"/docs/references/2.14/changelog","default":false,"active":false,"folderId":"a015c489"},{"version":"2.15","label":"v2.15","link":"/docs/references/changelog","default":true,"active":false,"folderId":"a015c489"},{"version":"Preview","label":"Preview","link":"/docs/references/preview/changelog","default":false,"active":true,"folderId":"a015c489"}],"sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml","oas-docs/references/@Preview/rest-api/api.intercom.io.yaml":"oas-docs/references/@Preview/rest-api/api.intercom.io.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","replay-openapi"]},"type":"markdown"},"seo":{"title":"Changelog (Preview)","description":"Faster resolutions, higher CSAT, and lighter support volumes with the only platform to combine the power of automation and human customer support.","siteUrl":"https://developers.intercom.com","image":"/assets/og-image.9c9ef3a6cedbceee0e1d52fae2ffcce97f5a189639cf24e473331da9ad02c5f8.b1bff462.png","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"changelog-preview","__idx":0},"children":["Changelog (Preview)"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Preview API"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Preview API provides early access to new capabilities we're actively developing. It's suitable for production use, and we're continuing to refine it based on customer feedback. We may make iterative improvements to Preview endpoints, including adding new fields or refining existing ones. When changes are not backward-compatible, we'll communicate them in advance."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For changes that have been updated across all versions, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/build-an-integration/learn-more/rest-apis/unversioned-changes"},"children":["Unversioned changes"]}," page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/build-an-integration/learn-more/rest-apis/api-changelog#about-breaking-changes-in-the-intercom-api"},"children":["breaking changes"]}," in this version, which are detailed below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"side-conversations-api","__idx":1},"children":["Side Conversations API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /conversations/{id}/side_conversations"]}," endpoint is now available for retrieving side conversations (internal teammate threads) associated with a conversation. Results are paginated and include the full conversation parts for each side conversation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New Endpoint:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/unstable/rest-api/api.intercom.io/Conversations/listSideConversations"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /conversations/{id}/side_conversations"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Query Parameters:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," (optional) - Page number of results to return (default: 1)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_page"]}," (optional) - Number of side conversations per page, between 1 and 50 (default: 25)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"side_conversation.list\",\n \"side_conversations\": [\n {\n \"side_conversation_id\": \"456\",\n \"conversation_parts\": [\n {\n \"type\": \"conversation_part\",\n \"id\": \"789\",\n \"part_type\": \"comment\",\n \"body\": \"

Internal note about this issue

\",\n \"author\": {\n \"type\": \"admin\",\n \"id\": \"123\",\n \"name\": \"Jane Example\",\n \"email\": \"jane@example.com\"\n }\n }\n ],\n \"total_count\": 1\n }\n ],\n \"total_count\": 1,\n \"pages\": {\n \"type\": \"pages\",\n \"page\": 1,\n \"per_page\": 25,\n \"total_pages\": 1\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth Scope:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read_conversations"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"company-activity-tracking-via-api","__idx":2},"children":["Company Activity Tracking via API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /companies"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /companies/{id}"]}," endpoints now accept an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update_last_request_at"]}," boolean parameter. When set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", the company's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_request_at"]}," field is updated to the current time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is useful for workspaces that manage companies via the REST API and need to keep the \"Last seen\" value up to date. Requires the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_users_companies"]}," OAuth scope."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"search-activity-logs-api","__idx":3},"children":["Search Activity Logs API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /admins/activity_logs/search"]}," endpoint is now available for searching and filtering admin activity logs. This provides a dedicated search endpoint with event type filtering capabilities."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New Endpoint:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Admins/searchActivityLogs"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /admins/activity_logs/search"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request Body Parameters:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at_after"]}," (optional) - Start date as a UNIX timestamp (defaults to 30 days ago)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at_before"]}," (optional) - End date as a UNIX timestamp"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_types"]}," (optional) - Array of event type strings to filter by"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," (optional) - Page number of results to return (default: 1)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_page"]}," (optional) - Number of results per page, between 1 and 250 (default: 20)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"created_at_after\": \"1677253093\",\n \"created_at_before\": \"1677861493\",\n \"event_types\": [\"app_name_change\", \"message_state_change\"]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Admins/listActivityLogEventTypes"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /admins/activity_log_event_types"]}]}," endpoint to retrieve all valid event type values."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint requires the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read_admins"]}," OAuth scope."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"content-snippets-api","__idx":4},"children":["Content Snippets API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["New endpoints to manage content snippets via the public API. Content snippets are reusable pieces of content that power Fin (AI agent) and Copilot responses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoints:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /content_snippets"]}," - List all content snippets (paginated)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /content_snippets/{id}"]}," - Retrieve a single content snippet"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /content_snippets"]}," - Create a new content snippet"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /content_snippets/{id}"]}," - Update an existing content snippet"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth Scope:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read_write_content_snippets"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /content_snippets\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"list\",\n \"data\": [\n {\n \"type\": \"content_snippet\",\n \"id\": \"123\",\n \"title\": \"How to reset your password\",\n \"locale\": \"en\",\n \"json_blocks\": [\n { \"type\": \"paragraph\", \"text\": \"Navigate to Settings > Security > Reset password.\" }\n ],\n \"chatbot_availability\": 1,\n \"copilot_availability\": 1,\n \"created_at\": 1663597223,\n \"updated_at\": 1663597223\n }\n ],\n \"total_count\": 1,\n \"page\": 1,\n \"per_page\": 50,\n \"total_pages\": 1\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"real-time-team-metrics","__idx":5},"children":["Real-Time Team Metrics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /teams/{team_id}/metrics"]}," endpoint is now available, providing real-time per-admin conversation metrics (open, idle, snoozed counts) for a given team. This is designed for workforce management integrations that need to monitor agent workload in real time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /teams/{team_id}/metrics"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Path Parameters:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["team_id"]}," - The ID of the team to retrieve metrics for. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /teams"]}," to list available team IDs."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Optional Parameters:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idle_threshold"]}," - Seconds after which an open conversation is considered idle (default: 1800, clamped to 1–86400)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /teams/42/metrics\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"team_metric.list\",\n \"data\": [\n {\n \"type\": \"team_metric\",\n \"admin_id\": \"123\",\n \"open\": 5,\n \"idle\": 2,\n \"snoozed\": 1\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint requires the real-time monitoring feature to be enabled for your workspace and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read_admins"]}," OAuth scope."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete documentation, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Teams/getTeamMetrics"},"children":["Team Metrics API Reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"email-history-in-conversation-source","__idx":6},"children":["Email History in Conversation Source"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /conversations/{id}"]}," endpoint now supports an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_email_history"]}," query parameter. When set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}," object of the conversation (email) will include an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email_message_metadata"]}," field containing:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message_id"]}," — the unique identifier from the email's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Message-ID"]}," header"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject"]}," — the subject of the email"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email_address_headers"]}," — a list of an email address headers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["history"]}," — the HTML content of any quoted or forwarded email history from the initial inbound message"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Updated Endpoint:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /conversations/{id}?include_email_history=true"]}," — returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email_message_metadata"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}," object"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["history"]}," is only available for the conversation source (initial part), not for individual conversation parts. This parameter is not available on list/search endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-deleted-conversations-api","__idx":7},"children":["List Deleted Conversations API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can now retrieve a list of deleted conversation IDs and their deletion timestamps using the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /conversations/deleted"]}," endpoint."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Try Listing Deleted Conversations"]},{"$$mdtype":"Tag","name":"ReplayOpenApi","attributes":{"descriptionFile":"oas-docs/references/@Preview/rest-api/api.intercom.io.yaml","operationId":"listDeletedConversationIds","parameters":{},"options":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-fin_voiceconversationconversation_id-added","__idx":8},"children":["GET /fin_voice/conversation/{conversation_id} added"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Added missing endpoint for retrieving Fin Voice calls associated with a conversation ID. Also backfilled to v2.15."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fin-agent-api-new-replying-status-for-intermediate-reply-events","__idx":9},"children":["Fin Agent API: New ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["replying"]}," status for intermediate reply events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fin_replied"]}," webhook event now uses a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["replying"]}," status for intermediate reply parts, and a separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fin_status_updated"]}," event with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["awaiting_user_reply"]}," fires as a \"done\" signal when Fin has finished replying. This replaces the previous behavior where every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fin_replied"]}," event had ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: awaiting_user_reply"]},", making it impossible to distinguish intermediate replies from the final one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Before:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"fin_replied (status: awaiting_user_reply) — part 1\nfin_replied (status: awaiting_user_reply) — part 2\nfin_replied (status: awaiting_user_reply) — part 3\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["After:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"fin_replied (status: replying) — part 1\nfin_replied (status: replying) — part 2\nfin_replied (status: replying) — part 3\nfin_status_updated (status: awaiting_user_reply) — done signal\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What changed:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fin_replied"]}," event: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," enum now includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["replying"]}," (new default for intermediate replies) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["awaiting_user_reply"]}," (legacy)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fin_status_updated"]}," event: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," enum now includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["awaiting_user_reply"]}," in addition to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["escalated"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resolved"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complete"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clients should update their integrations to listen for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fin_status_updated"]}," event with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: awaiting_user_reply"]}," as the signal that Fin is done replying and the user can respond."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"activity-log-event-types-api","__idx":10},"children":["Activity Log Event Types API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new endpoint lets you retrieve all possible event type values for admin activity logs. Use these values to understand what actions are trackable and to filter results when querying the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Admins/listActivityLogs"},"children":["Activity Logs API"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New Endpoint:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /admins/activity_log_event_types"]}," - List all activity log event types"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"activity_log_event_type.list\",\n \"event_types\": [\n \"admin_login_success\",\n \"admin_logout\",\n \"app_name_change\",\n \"message_state_change\"\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth Scope Required:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Read admins and teammates"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete documentation, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Admins/listActivityLogEventTypes"},"children":["Activity Log Event Types API Reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conversations-api-retain_metrics-parameter-for-conversation-deletion","__idx":11},"children":["Conversations API: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retain_metrics"]}," parameter for conversation deletion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Conversations/deleteConversation"},"children":["Delete a conversation"]}," endpoint now supports a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retain_metrics"]}," query parameter that controls how conversation data is deleted:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retain_metrics=true"]}," (default)"]},": Deletes the conversation while retaining reporting data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retain_metrics=false"]}]},": Deletes the conversation and all associated reporting data."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Required scope for retain_metrics=false"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retain_metrics=false"]}," requires the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete_conversations_and_metrics"]}," OAuth scope. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/build-an-integration/learn-more/authentication/oauth-scopes"},"children":["OAuth Scopes"]}," for details."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X DELETE https://api.intercom.io/conversations/123?retain_metrics=false \\\n -H 'Authorization: Bearer ' \\\n -H 'Accept: application/json' \\\n -H 'Intercom-Version: Preview'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more info, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://www.intercom.com/help/en/articles/13885146-deleting-a-conversation"},"children":["this help center article"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"folder-management-api","__idx":12},"children":["Folder Management API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new top-level Folders API is now available at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/folders"]}," for organizing content into hierarchical folder structures."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New endpoints:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /folders"]}," — List all folders (supports pagination and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parent_folder_id"]}," filter)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /folders"]}," — Create a new folder"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /folders/{id}"]}," — Retrieve a folder"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /folders/{id}"]}," — Update a folder"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /folders/{id}"]}," — Delete a folder (must be empty)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Article and Internal Article changes:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["folder_id"]}," field has been added to article and internal article responses, as well as create and update request payloads, allowing you to organize articles into folders."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/internal_articles/search"]}," endpoint's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["folder_id"]}," parameter now searches recursively through descendant folders."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ticket-state-change-tracking","__idx":13},"children":["Ticket state change tracking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Ticket object now includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["previous_ticket_state_id"]}," field that returns the ID of the ticket's previous state. This enables tracking ticket state transitions for reporting and compliance. The field returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when no state change history exists."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"company-notes-api","__idx":14},"children":["Company Notes API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can now create notes on company records via the API using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /companies/{company_id}/notes"]},", mirroring the existing contact notes functionality. The request and response format is identical to contact notes, with an optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["admin_id"]}," parameter that defaults to the token owner. Notes are polymorphic — a single note belongs to either a contact or a company, never both."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"admin-role-now-included-in-api-responses","__idx":15},"children":["Admin role now included in API responses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The admin object returned by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /admins"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /admins/{id}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /me"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /admins/{id}/away"]}," now includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role"]}," attribute when the admin has a role assigned. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role"]}," object contains the role ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"admin\",\n \"id\": \"1295\",\n \"name\": \"Joe Example\",\n \"role\": {\n \"type\": \"role\",\n \"id\": \"456\",\n \"name\": \"Support Agent\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Admins with custom per-user permissions (no role assigned) will not have the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role"]}," field."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conversations-api-display_as-parameter-behavior","__idx":16},"children":["Conversations API: display_as parameter behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["display_as"]}," query parameter in the Retrieve Conversation and List Conversation Parts endpoints now affects both the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject"]}," fields of conversation messages when set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plaintext"]},". By default, both fields are returned in HTML format."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conversation-webhook-serialization-alignment","__idx":17},"children":["Conversation Webhook Serialization Alignment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Conversation webhook payloads now use the same serialization format as API responses:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Statistics date fields"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_contact_reply_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_assignment_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_admin_reply_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_close_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_assignment_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_assignment_admin_reply_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_contact_reply_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_admin_reply_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_close_at"]},") now return Unix timestamp integers instead of ISO8601 strings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject"]}," fields"]}," now return plain text instead of HTML."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"data-connectors-api","__idx":18},"children":["Data Connectors API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We've added a new Data Connectors API that lets you create, update, delete, and list your data connectors, plus view their execution history. Data connectors allow you to make HTTP requests to external APIs from Intercom workflows and AI agents."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoints:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /data_connectors"]}," - Create a new data connector"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /data_connectors/{id}"]}," - Update a data connector (fields, state transitions)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /data_connectors/{id}"]}," - Delete a data connector"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /data_connectors"]}," - List all data connectors (paginated)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /data_connectors/{id}"]}," - Retrieve a single data connector with full detail"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /data_connectors/{id}/execution_results"]}," - List execution results"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /data_connectors/{id}/execution_results/{id}"]}," - Retrieve a single execution result"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key Features:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create in draft"]},": New connectors start in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draft"]}," state — configure URL, headers, data inputs, and audiences before publishing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Audience targeting"]},": Control which user types (leads, users, visitors) can trigger the connector"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Safe deletion"]},": Returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}," if the connector is in use or not in draft state"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cursor-based pagination"]},": Navigate through data connectors and execution results using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["starting_after"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_page"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Filtering"]},": Filter execution results by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_type"]},", and time range"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Opt-in bodies"]},": Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_bodies=true"]}," to include request/response bodies in execution results"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Opt-in request URL"]},": Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_request_url=true"]}," to include the sanitised request URL"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth Scope Required:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Read data connectors"]}," (read-only) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Read and write data connectors"]}," (create/update/delete)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete documentation and examples, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Data-Connectors"},"children":["Data Connectors API Reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"new-data-connector-execution-webhook-topic","__idx":19},"children":["New Data Connector execution webhook topic"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can now receive real-time notifications when Data Connector actions complete execution using the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data_connector.execution.completed"]}," webhook topic. This webhook provides operational visibility into connector execution outcomes, including success/failure status, HTTP response codes, error categorization, and execution timing. See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/references/preview/webhooks/webhook-models"},"children":["webhook models"]}," for details on how to subscribe to execution events."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"macros-api","__idx":20},"children":["Macros API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We've added a new Macros API that provides programmatic access to saved replies (macros) in Intercom. This API enables external applications to retrieve and display your team's pre-written responses, making it easier to integrate Intercom macros with third-party tools and workflows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New Endpoints:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /macros"]}," - List all available macros with pagination"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /macros/{id}"]}," - Retrieve a specific macro by ID"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key Features:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cursor-based pagination"]},": Navigate through large sets of macros efficiently using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["starting_after"]}," parameter with Base64-encoded cursors"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Smart placeholder transformation"]},": Macros containing Intercom placeholders (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{user.name}}"]},") are automatically transformed to XML-like attributes (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[""]},") for easier parsing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flexible filtering"]},": Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated_since"]}," parameter to retrieve only recently modified macros"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Team visibility controls"]},": Respects macro visibility settings, showing only macros available to the authenticated user's teams"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Channel availability"]},": Each macro indicates where it can be used (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messenger"]},", or both)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth Scope Required:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READ_CONVERSATIONS"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use Cases:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Integration with training platforms like Solidroad for customer service simulations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Building custom macro management interfaces"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exporting macros for documentation or backup purposes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Analyzing macro usage and content across your organization"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.intercom.io/macros?per_page=10 \\\n -H 'Authorization: Bearer ' \\\n -H 'Accept: application/json' \\\n -H 'Intercom-Version: Preview'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"list\",\n \"data\": [\n {\n \"type\": \"macro\",\n \"id\": \"123\",\n \"name\": \"Order Status Update\",\n \"body\": \"

Hi , your order is ready!

\",\n \"body_text\": \"Hi there, your order is ready!\",\n \"created_at\": \"2025-07-17T11:18:08.000Z\",\n \"updated_at\": \"2025-07-17T15:30:24.000Z\",\n \"visible_to\": \"everyone\",\n \"visible_to_team_ids\": [],\n \"available_on\": [\"inbox\", \"messenger\"]\n }\n ],\n \"pages\": {\n \"type\": \"pages\",\n \"per_page\": 10,\n \"next\": {\n \"starting_after\": \"WzE3MTk0OTM3NTcuMCwgIjEyMyJd\"\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important Notes:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["This API is currently available in the Preview version only"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Placeholders in macro bodies are transformed from Intercom format to XML-like attributes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The pagination cursor encodes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[updated_at, id]"]}," for stable ordering"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Maximum 150 macros can be retrieved per request"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete documentation and more examples, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/macros/"},"children":["Macros API Reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"new-whatsapp-message-status-api","__idx":21},"children":["New WhatsApp Message status API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/whatsapp/getwhatsappmessagestatus"},"children":["WhatsApp Message status API"]}," is now available in the Preview version. This endpoint returns paginated status events for WhatsApp messages sent via the Outbound module, providing information about delivery state and related message details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"enforcement-of-ticket-permissions-on-the-conversations-api","__idx":22},"children":["Enforcement of ticket permissions on the Conversations API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Starting in early August 2024, accessing a ticket directly through the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Conversations/retrieveConversation/"},"children":["Conversations API"]}," will requires the \"Read tickets\" or \"Write tickets\" scope, as appropriate. When ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Conversations/listConversations/"},"children":["listing conversations"]}," or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Conversations/searchConversations/"},"children":["searching conversations"]},", tickets will only be returned in the results if the caller has the \"Read tickets\" scope."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Breaking permission changes"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Previously, tickets were accessible through the Conversations API using only the \"Read conversations\" or \"Write conversations\" scope(s). Any apps relying on this behaviour will need to add the appropriate ticket permission, and have users reauthenticate."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"new-searchable-contact-attribute","__idx":23},"children":["New Searchable Contact Attribute"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We added ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted_phone"]}," as a searchable attribute for contacts. This is the contact's phone number normalized to the E164 format."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reporting-data-export-api-qualified_id-for-attribute-disambiguation","__idx":24},"children":["Reporting Data Export API: qualified_id for Attribute Disambiguation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Reporting Data Export API now includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_id"]}," field in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_datasets"]}," response to uniquely identify attributes across different types."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem Solved:"]}," ","Custom attributes can have the same name across different types (e.g., a \"Brand\" attribute might exist for both user custom data and conversation custom data). Previously, using just the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," field could result in ambiguous attribute selection."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New Field:"]}," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_id"]}," field uses a namespaced format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"type.name\""]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"people.Brand\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"conversation.Brand\""]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Available Prefixes:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["people"]}," - User custom data attributes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["company"]}," - Company custom data attributes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversation"]}," - Conversation custom data attributes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ticket"]}," - Ticket attributes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system"]}," - System-defined attributes"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"list\",\n \"data\": [\n {\n \"id\": \"conversation\",\n \"name\": \"Conversation\",\n \"attributes\": [\n {\n \"id\": \"Brand\",\n \"qualified_id\": \"people.Brand\",\n \"name\": \"Brand\"\n }\n ]\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Usage:"]}," ","When calling the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enqueue"]}," endpoint, you must use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_id"]}," values in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["attribute_ids"]}," array. The simple ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," is no longer accepted — use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_id"]}," from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_datasets"]}," response to ensure unambiguous attribute selection."]}]},"headings":[{"value":"Changelog (Preview)","id":"changelog-preview","depth":1},{"value":"Side Conversations API","id":"side-conversations-api","depth":2},{"value":"Company Activity Tracking via API","id":"company-activity-tracking-via-api","depth":2},{"value":"Search Activity Logs API","id":"search-activity-logs-api","depth":2},{"value":"Content Snippets API","id":"content-snippets-api","depth":2},{"value":"Real-Time Team Metrics","id":"real-time-team-metrics","depth":2},{"value":"Email History in Conversation Source","id":"email-history-in-conversation-source","depth":2},{"value":"List Deleted Conversations API","id":"list-deleted-conversations-api","depth":2},{"value":"GET /fin_voice/conversation/{conversation_id} added","id":"get-fin_voiceconversationconversation_id-added","depth":2},{"value":"Fin Agent API: New replying status for intermediate reply events","id":"fin-agent-api-new-replying-status-for-intermediate-reply-events","depth":2},{"value":"Activity Log Event Types API","id":"activity-log-event-types-api","depth":2},{"value":"Conversations API: retain_metrics parameter for conversation deletion","id":"conversations-api-retain_metrics-parameter-for-conversation-deletion","depth":2},{"value":"Folder Management API","id":"folder-management-api","depth":2},{"value":"Ticket state change tracking","id":"ticket-state-change-tracking","depth":2},{"value":"Company Notes API","id":"company-notes-api","depth":2},{"value":"Admin role now included in API responses","id":"admin-role-now-included-in-api-responses","depth":2},{"value":"Conversations API: display_as parameter behavior","id":"conversations-api-display_as-parameter-behavior","depth":2},{"value":"Conversation Webhook Serialization Alignment","id":"conversation-webhook-serialization-alignment","depth":2},{"value":"Data Connectors API","id":"data-connectors-api","depth":2},{"value":"New Data Connector execution webhook topic","id":"new-data-connector-execution-webhook-topic","depth":2},{"value":"Macros API","id":"macros-api","depth":2},{"value":"New WhatsApp Message status API","id":"new-whatsapp-message-status-api","depth":2},{"value":"Enforcement of ticket permissions on the Conversations API","id":"enforcement-of-ticket-permissions-on-the-conversations-api","depth":2},{"value":"New Searchable Contact Attribute","id":"new-searchable-contact-attribute","depth":2},{"value":"Reporting Data Export API: qualified_id for Attribute Disambiguation","id":"reporting-data-export-api-qualified_id-for-attribute-disambiguation","depth":2}],"frontmatter":{"seo":{"title":"Changelog (Preview)"}},"lastModified":"2026-04-10T17:03:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/references/preview/changelog","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}