chore: Swagger doc for Conversation meta API (#4394)

fixes: https://github.com/chatwoot/chatwoot/issues/4327

swagger/definitions/resource/extension/conversation/list.yml

@@ -10,6 +10,8 @@ properties:
             type: number
           unassigned_count:
             type: number
+          assigned_count:
+            type: number
           all_count:
             type: number
       payload:

swagger/parameters/index.yml

@@ -16,24 +16,24 @@ hook_id:
 source_id:
   $ref: ./source_id.yml
 
+contact_sort_param:
+  $ref: ./contact_sort.yml
+
 conversation_id:
   $ref: ./conversation_id.yml
 
+custom_filter_id:
+  $ref: ./custom_filter_id.yml
+
 message_id:
   $ref: ./message_id.yml
 
-contact_sort_param:
-  $ref: ./contact_sort.yml
-
 page:
   $ref: ./page.yml
 
 platform_user_id:
   $ref: ./platform_user_id.yml
 
-custom_filter_id:
-  $ref: ./custom_filter_id.yml
-
 report_type:
   $ref: ./report_type.yml
 

swagger/paths/application/conversation/index.yml

@@ -12,17 +12,22 @@ get:
       in: query
       type: string
       enum: ['me', 'unassigned', 'all', 'assigned']
-      required: true
+      default: 'all'
+      description: Filter conversations by assignee type.
     - name: status
       in: query
       type: string
-      enum: ['open', 'resolved', 'pending']
+      enum: ['open', 'resolved', 'pending', 'snoozed']
-      required: true
+      default: 'open'
-    - name: page
+      description: Filter by conversation status.
+    - name: q
+      in: query
+      type: string
+      description: Filters conversations with messages containing the search term
+    - name: inbox_id
       in: query
       type: integer
-      required: true
+    - name: team_id
-    - name: inbox_id
       in: query
       type: integer
     - name: labels
@@ -30,7 +35,12 @@ get:
       type: array
       items:
         type: string
-
+    - name: page
+      in: query
+      type: integer
+      default: 1
+      description: paginate through conversations
+   
   responses:
     200:
       description: Success

swagger/paths/application/conversation/meta.yml

@@ -0,0 +1,53 @@
+parameters:
+  - $ref: '#/parameters/account_id'
+
+get:
+  tags:
+    - Conversations
+  operationId: conversationListMeta
+  description: Get open, unassigned and all Conversation counts
+  summary: Get Conversation Counts
+  parameters:
+    - name: status
+      in: query
+      type: string
+      enum: ['open', 'resolved', 'pending', 'snoozed']
+      default: 'open'
+      description: Filter by conversation status.
+    - name: q
+      in: query
+      type: string
+      description: Filters conversations with messages containing the search term
+    - name: inbox_id
+      in: query
+      type: integer
+    - name: team_id
+      in: query
+      type: integer
+    - name: labels
+      in: query
+      type: array
+      items:
+        type: string
+
+  responses:
+    200:
+      description: Success
+      schema:
+        type: object
+        properties:
+          meta:
+            type: object
+            properties:
+              mine_count:
+                type: number
+              unassigned_count:
+                type: number
+              assigned_count:
+                type: number
+              all_count:
+                type: number
+    400:
+      description: Bad Request Error
+      schema:
+        $ref: '#/definitions/bad_request_error'

swagger/paths/index.yml

@@ -209,6 +209,8 @@
 
 
 # Conversations
+/api/v1/accounts/{account_id}/conversations/meta:
+  $ref: ./application/conversation/meta.yml
 /api/v1/accounts/{account_id}/conversations:
   $ref: ./application/conversation/index.yml
 /api/v1/accounts/{account_id}/conversations/filter:

swagger/swagger.json

@@ -2135,6 +2135,93 @@
         }
       }
     },
+    "/api/v1/accounts/{account_id}/conversations/meta": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Conversations"
+        ],
+        "operationId": "conversationListMeta",
+        "description": "Get open, unassigned and all Conversation counts",
+        "summary": "Get Conversation Counts",
+        "parameters": [
+          {
+            "name": "status",
+            "in": "query",
+            "type": "string",
+            "enum": [
+              "open",
+              "resolved",
+              "pending",
+              "snoozed"
+            ],
+            "default": "open",
+            "description": "Filter by conversation status."
+          },
+          {
+            "name": "q",
+            "in": "query",
+            "type": "string",
+            "description": "Filters conversations with messages containing the search term"
+          },
+          {
+            "name": "inbox_id",
+            "in": "query",
+            "type": "integer"
+          },
+          {
+            "name": "team_id",
+            "in": "query",
+            "type": "integer"
+          },
+          {
+            "name": "labels",
+            "in": "query",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "type": "object",
+              "properties": {
+                "meta": {
+                  "type": "object",
+                  "properties": {
+                    "mine_count": {
+                      "type": "number"
+                    },
+                    "unassigned_count": {
+                      "type": "number"
+                    },
+                    "assigned_count": {
+                      "type": "number"
+                    },
+                    "all_count": {
+                      "type": "number"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request Error",
+            "schema": {
+              "$ref": "#/definitions/bad_request_error"
+            }
+          }
+        }
+      }
+    },
     "/api/v1/accounts/{account_id}/conversations": {
       "parameters": [
         {
@@ -2159,7 +2246,8 @@
               "all",
               "assigned"
             ],
-            "required": true
+            "default": "all",
+            "description": "Filter conversations by assignee type."
           },
           {
             "name": "status",
@@ -2168,21 +2256,28 @@
             "enum": [
               "open",
               "resolved",
-              "pending"
+              "pending",
+              "snoozed"
             ],
-            "required": true
+            "default": "open",
+            "description": "Filter by conversation status."
           },
           {
-            "name": "page",
+            "name": "q",
             "in": "query",
-            "type": "integer",
+            "type": "string",
-            "required": true
+            "description": "Filters conversations with messages containing the search term"
           },
           {
             "name": "inbox_id",
             "in": "query",
             "type": "integer"
           },
+          {
+            "name": "team_id",
+            "in": "query",
+            "type": "integer"
+          },
           {
             "name": "labels",
             "in": "query",
@@ -2190,6 +2285,13 @@
             "items": {
               "type": "string"
             }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "type": "integer",
+            "default": 1,
+            "description": "paginate through conversations"
           }
         ],
         "responses": {
@@ -5314,6 +5416,9 @@
                 "unassigned_count": {
                   "type": "number"
                 },
+                "assigned_count": {
+                  "type": "number"
+                },
                 "all_count": {
                   "type": "number"
                 }
@@ -5595,20 +5700,6 @@
       "type": "string",
       "description": "Id of the session for which the conversation is created.\n\n\n\n Source Ids can be obtained through contactable inboxes API or via generated.<br/><br/>Website: Chatwoot generated string which can be obtained from webhook events. <br/> Phone Channels(Twilio): Phone number in e164 format <br/> Email Channels: Contact Email address <br/> API Channel: Any Random String"
     },
-    "conversation_id": {
-      "in": "path",
-      "name": "conversation_id",
-      "type": "integer",
-      "required": true,
-      "description": "The numeric ID of the conversation"
-    },
-    "message_id": {
-      "in": "path",
-      "name": "message_id",
-      "type": "integer",
-      "required": true,
-      "description": "The numeric ID of the message"
-    },
     "contact_sort_param": {
       "in": "query",
       "name": "sort",
@@ -5626,6 +5717,27 @@
       "required": false,
       "description": "The attribute by which list should be sorted"
     },
+    "conversation_id": {
+      "in": "path",
+      "name": "conversation_id",
+      "type": "integer",
+      "required": true,
+      "description": "The numeric ID of the conversation"
+    },
+    "custom_filter_id": {
+      "in": "path",
+      "name": "custom_filter_id",
+      "type": "integer",
+      "required": true,
+      "description": "The numeric ID of the custom filter"
+    },
+    "message_id": {
+      "in": "path",
+      "name": "message_id",
+      "type": "integer",
+      "required": true,
+      "description": "The numeric ID of the message"
+    },
     "page": {
       "in": "query",
       "name": "page",
@@ -5641,13 +5753,6 @@
       "required": true,
       "description": "The numeric ID of the user on the platform"
     },
-    "custom_filter_id": {
-      "in": "path",
-      "name": "custom_filter_id",
-      "type": "integer",
-      "required": true,
-      "description": "The numeric ID of the custom filter"
-    },
     "report_type": {
       "in": "query",
       "name": "report_type",