conversation delete endpoint retain metrics and permission (#379)

* conversation delete endpoint retain metrics and permission

* changes

* Rename OAuth scope from permanently_delete_conversations to delete_conversations_and_metrics

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: marcmlc

descriptions/0/api.intercom.io.yaml

@@ -6874,6 +6874,15 @@ paths:
         required: true
         schema:
           type: integer
+      - name: retain_metrics
+        in: query
+        required: false
+        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 `delete_conversations_and_metrics` OAuth scope.
+        example: true
+        schema:
+          type: boolean
       tags:
       - Conversations
       operationId: deleteConversation
@@ -6882,7 +6891,15 @@ 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)**: 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`**: 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 `delete_conversations_and_metrics` OAuth scope.
+        {% /admonition %}
       responses:
         '200':
           description: successful