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

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:

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"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }

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"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }