From 7e708e1352f8b301a476b4faf5f285488bd90fed Mon Sep 17 00:00:00 2001 From: Varshini Suresh Date: Wed, 4 Mar 2026 14:11:20 +0530 Subject: [PATCH 1/2] Add GET /conversations/deleted endpoint to Unstable API spec Add new endpoint to retrieve deleted conversation IDs with deletion timestamps for compliance and audit purposes. Changes: - Added /conversations/deleted GET endpoint with pagination support - Added deleted_conversation_item schema - Added deleted_conversation_list schema - Fixed response structure to use 'conversations' array key (consistent with conversation_list) - All examples use updated_at field for deletion timestamp Co-Authored-By: Claude Haiku 4.5 --- descriptions/0/api.intercom.io.yaml | 138 ++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index b64af60..c71ce42 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -8557,6 +8557,100 @@ paths: summary: Bad request value: ticket_type_id: '54' + "/conversations/deleted": + get: + summary: List all deleted conversation IDs + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + required: false + description: The page of results to fetch. Defaults to first page + example: 1 + schema: + type: integer + - name: per_page + in: query + required: false + description: How many results per page + schema: + type: integer + default: 20 + maximum: 60 + - name: order + in: query + required: false + description: "`asc` or `desc`. Returns the conversation IDs in ascending or descending order. Defaults to desc" + example: desc + schema: + type: string + tags: + - Conversations + operationId: listDeletedConversationIds + description: |+ + List all deleted conversation IDs. + + {% admonition type="warning" name="Pagination" %} + You can use pagination to limit the number of results returned. The default is `20` results per page. You can navigate to next pages using the `page` param. + {% /admonition %} + responses: + '200': + description: View all deleted conversation IDs + content: + application/json: + examples: + successful: + value: + type: conversations.list + total_count: 4 + pages: + type: pages + next: https://api.intercom.io/conversations/deleted?per_page=2&order=desc&page=2 + page: 1 + per_page: 2 + total_pages: 2 + conversations: + - type: conversation + id: '512' + metrics_retained: false + updated_at: 1734537460 + - type: conversation + id: '513' + metrics_retained: true + updated_at: 1734537400 + schema: + "$ref": "#/components/schemas/deleted_conversation_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '400': + description: Resource not available + content: + application/json: + examples: + Resource not available: + value: + type: error.list + request_id: 7a80b950-b392-499f-85db-ea7c6c424d37 + errors: + - code: intercom_version_invalid + message: Requested resource is not available in current API version. + schema: + "$ref": "#/components/schemas/error" "/custom_channel_events/notify_new_conversation": post: summary: Notify Intercom of a new conversation created in a custom channel @@ -18506,6 +18600,50 @@ components: type: boolean description: Whether the conversation is deleted or not. example: true + deleted_conversation_item: + title: Conversation + type: object + x-tags: + - Conversation + description: A deleted conversation record containing its ID, metrics retained status and deletion timestamp. + properties: + type: + type: string + description: String representing the object's type. Always has the value `conversation`. + example: 'conversation' + id: + type: string + description: The ID of the deleted conversation. + example: '512' + metrics_retained: + type: boolean + description: Whether reporting metrics are retained for this conversation ID + example: true + updated_at: + type: integer + format: date-time + description: The time when the conversation was deleted. + example: 1734537745 + deleted_conversation_list: + title: Conversations + type: object + description: A paginated list of deleted conversation IDs. + properties: + type: + type: string + description: String representing the object's type. Always has the value `conversations.list`. + example: conversations.list + conversations: + type: array + description: The list of deleted conversation IDs. + items: + "$ref": "#/components/schemas/deleted_conversation_item" + total_count: + type: integer + description: Total number of items available. + example: 10 + pages: + "$ref": "#/components/schemas/pages_link" conversation_first_contact_reply: title: First contact reply type: object From 63e2f3f805fba3ca2f80d613b735df4087508aec Mon Sep 17 00:00:00 2001 From: Varshini Suresh Date: Wed, 4 Mar 2026 15:35:36 +0530 Subject: [PATCH 2/2] Change field name to deleted_at instead of updated_at --- descriptions/0/api.intercom.io.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index c71ce42..530b5ad 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -8616,11 +8616,11 @@ paths: - type: conversation id: '512' metrics_retained: false - updated_at: 1734537460 + deleted_at: 1734537460 - type: conversation id: '513' metrics_retained: true - updated_at: 1734537400 + deleted_at: 1734537400 schema: "$ref": "#/components/schemas/deleted_conversation_list" '401': @@ -18619,7 +18619,7 @@ components: type: boolean description: Whether reporting metrics are retained for this conversation ID example: true - updated_at: + deleted_at: type: integer format: date-time description: The time when the conversation was deleted.