From 1024a8eca0022b7fef1fe7c25afad98b79897a03 Mon Sep 17 00:00:00 2001
From: Marc <97827744+marcmlc@users.noreply.github.com>
Date: Tue, 24 Feb 2026 11:04:40 +0000
Subject: [PATCH 1/2] conversation delete endpoint retain metrics and
 permission

---
 descriptions/0/api.intercom.io.yaml | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index f4f7d55..e6a9a57 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -6750,6 +6750,16 @@ paths:
         required: true
         schema:
           type: integer
+      - name: retain_metrics
+        in: query
+        required: false
+        description: If true (default), soft deletes the conversation but retains it
+          in reporting. If false, permanently deletes all conversation data including
+          metrics. Setting to false requires the `permanently_delete_conversations`
+          OAuth scope.
+        example: true
+        schema:
+          type: boolean
       tags:
       - Conversations
       operationId: deleteConversation
@@ -6758,7 +6768,11 @@ paths:
         Deleting a conversation is permanent and cannot be reversed.
         {% /admonition %}
 
-        Deleting a conversation permanently removes it from the inbox. All sensitive data is deleted, including admin and user replies, conversation attributes, uploads, and related content. The conversation will still appear in reporting, though some data may be incomplete due to the deletion.
+        You can delete a single conversation. The behavior depends on the `retain_metrics` parameter:
+
+        - **With `retain_metrics=true` (default)**: Soft deletes the conversation, removing sensitive data (admin and user replies, conversation attributes, uploads, and related content). The conversation will still appear in reporting, though some data may be incomplete due to the deletion.
+
+        - **With `retain_metrics=false`**: Permanently deletes ALL conversation data including metrics. This requires the `permanently_delete_conversations` OAuth scope. The conversation will be completely removed from both the inbox and all reporting.
       responses:
         '200':
           description: successful

From a54201c8e996e9c7f812f07017b69f3a0f81e71d Mon Sep 17 00:00:00 2001
From: Marc <97827744+marcmlc@users.noreply.github.com>
Date: Mon, 2 Mar 2026 10:35:49 +0100
Subject: [PATCH 2/2] changes

---
 descriptions/0/api.intercom.io.yaml | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index e6a9a57..0b0acb1 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -6753,10 +6753,9 @@ paths:
       - name: retain_metrics
         in: query
         required: false
-        description: If true (default), soft deletes the conversation but retains it
-          in reporting. If false, permanently deletes all conversation data including
-          metrics. Setting to false requires the `permanently_delete_conversations`
-          OAuth scope.
+        description: If true (default), deletes the conversation while retaining reporting
+          data. If false, deletes the conversation and all associated reporting data.
+          Setting to false requires the `permanently_delete_conversations` OAuth scope.
         example: true
         schema:
           type: boolean
@@ -6770,9 +6769,13 @@ paths:
 
         You can delete a single conversation. The behavior depends on the `retain_metrics` parameter:
 
-        - **With `retain_metrics=true` (default)**: Soft deletes the conversation, removing sensitive data (admin and user replies, conversation attributes, uploads, and related content). The conversation will still appear in reporting, though some data may be incomplete due to the deletion.
+        - **With `retain_metrics=true` (default)**: Deletes the conversation while retaining reporting data. The conversation will still appear in reporting, though some data may be incomplete due to the deletion.
 
-        - **With `retain_metrics=false`**: Permanently deletes ALL conversation data including metrics. This requires the `permanently_delete_conversations` OAuth scope. The conversation will be completely removed from both the inbox and all reporting.
+        - **With `retain_metrics=false`**: Deletes the conversation and all associated reporting data. The conversation will be completely removed from both the inbox and all reporting.
+
+        {% admonition type="info" name="Required scope for retain_metrics=false" %}
+        Using `retain_metrics=false` requires the `permanently_delete_conversations` OAuth scope.
+        {% /admonition %}
       responses:
         '200':
           description: successful