From aba4e8bc53e4fcb9a3f277b4cb43f75cf45c5994 Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Wed, 10 Sep 2025 17:33:24 +0530 Subject: [PATCH] docs: Update conversation toggle API with snooze & pending (#12406) ## Changes - Update conversation toggle API with documentation of additional statuses and options which are supported - snoozed , snooze_until & pending fixes: https://github.com/chatwoot/chatwoot/issues/12137 --- .../conversation/toggle_status.yml | 32 ++++++++++++++-- swagger/swagger.json | 37 +++++++++++++++++-- swagger/tag_groups/application_swagger.json | 37 +++++++++++++++++-- 3 files changed, 97 insertions(+), 9 deletions(-) diff --git a/swagger/paths/application/conversation/toggle_status.yml b/swagger/paths/application/conversation/toggle_status.yml index 9c6f9ee6a..80cf47c65 100644 --- a/swagger/paths/application/conversation/toggle_status.yml +++ b/swagger/paths/application/conversation/toggle_status.yml @@ -2,7 +2,13 @@ tags: - Conversations operationId: toggle-status-of-a-conversation summary: Toggle Status -description: Toggles the status of the conversation between open and resolved +description: |- + Toggle the status of a conversation. Pass `status` to explicitly set the + conversation state. Use `snoozed` along with `snoozed_until` to snooze a + conversation until a specific time. If `snoozed_until` is omitted, the + conversation is snoozed until the next reply from the contact. Regardless + of the value provided, snoozed conversations always reopen on the next + reply from the contact. security: - userApiKey: [] - agentBotApiKey: [] @@ -17,16 +23,36 @@ requestBody: properties: status: type: string - enum: ['open', 'resolved', 'pending'] + enum: ['open', 'resolved', 'pending', 'snoozed'] description: The status of the conversation example: open + snoozed_until: + type: number + description: When status is `snoozed`, schedule the reopen time as a Unix timestamp in seconds. + If not provided, the conversation is snoozed until the next + customer reply. The conversation always reopens when the + customer replies. + example: 1757506877 responses: '200': description: Success content: application/json: schema: - $ref: '#/components/schemas/conversation_status_toggle' + type: object + properties: + meta: + type: object + payload: + type: object + properties: + success: + type: boolean + current_status: + type: string + enum: ['open', 'resolved', 'pending', 'snoozed'] + conversation_id: + type: number '404': description: Conversation not found content: diff --git a/swagger/swagger.json b/swagger/swagger.json index aa7455e7f..39022bf84 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -4673,7 +4673,7 @@ ], "operationId": "toggle-status-of-a-conversation", "summary": "Toggle Status", - "description": "Toggles the status of the conversation between open and resolved", + "description": "Toggle the status of a conversation. Pass `status` to explicitly set the\nconversation state. Use `snoozed` along with `snoozed_until` to snooze a\nconversation until a specific time. If `snoozed_until` is omitted, the\nconversation is snoozed until the next reply from the contact. Regardless\nof the value provided, snoozed conversations always reopen on the next\nreply from the contact.", "security": [ { "userApiKey": [] @@ -4697,10 +4697,16 @@ "enum": [ "open", "resolved", - "pending" + "pending", + "snoozed" ], "description": "The status of the conversation", "example": "open" + }, + "snoozed_until": { + "type": "number", + "description": "When status is `snoozed`, schedule the reopen time as a Unix timestamp in seconds. If not provided, the conversation is snoozed until the next customer reply. The conversation always reopens when the customer replies.", + "example": 1757506877 } } } @@ -4713,7 +4719,32 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/conversation_status_toggle" + "type": "object", + "properties": { + "meta": { + "type": "object" + }, + "payload": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "current_status": { + "type": "string", + "enum": [ + "open", + "resolved", + "pending", + "snoozed" + ] + }, + "conversation_id": { + "type": "number" + } + } + } + } } } } diff --git a/swagger/tag_groups/application_swagger.json b/swagger/tag_groups/application_swagger.json index a36443f81..b26b913bc 100644 --- a/swagger/tag_groups/application_swagger.json +++ b/swagger/tag_groups/application_swagger.json @@ -3070,7 +3070,7 @@ ], "operationId": "toggle-status-of-a-conversation", "summary": "Toggle Status", - "description": "Toggles the status of the conversation between open and resolved", + "description": "Toggle the status of a conversation. Pass `status` to explicitly set the\nconversation state. Use `snoozed` along with `snoozed_until` to snooze a\nconversation until a specific time. If `snoozed_until` is omitted, the\nconversation is snoozed until the next reply from the contact. Regardless\nof the value provided, snoozed conversations always reopen on the next\nreply from the contact.", "security": [ { "userApiKey": [] @@ -3094,10 +3094,16 @@ "enum": [ "open", "resolved", - "pending" + "pending", + "snoozed" ], "description": "The status of the conversation", "example": "open" + }, + "snoozed_until": { + "type": "number", + "description": "When status is `snoozed`, schedule the reopen time as a Unix timestamp in seconds. If not provided, the conversation is snoozed until the next customer reply. The conversation always reopens when the customer replies.", + "example": 1757506877 } } } @@ -3110,7 +3116,32 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/conversation_status_toggle" + "type": "object", + "properties": { + "meta": { + "type": "object" + }, + "payload": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "current_status": { + "type": "string", + "enum": [ + "open", + "resolved", + "pending", + "snoozed" + ] + }, + "conversation_id": { + "type": "number" + } + } + } + } } } }