chore: Add API documentation for teams (#2221)

Add API documentation for teams

Gemfile

@@ -112,7 +112,7 @@ group :development do
   gem 'web-console'
 
   # used in swagger build
-  gem 'json_refs', git: 'https://github.com/tzmfreedom/json_refs', ref: 'e32deb0'
+  gem 'json_refs', git: 'https://github.com/tzmfreedom/json_refs', ref: '131b11294fd6af9c428171f38516e6222a58c874'
 
   # When we want to squash migrations
   gem 'squasher'

Gemfile.lock

@@ -7,10 +7,10 @@ GIT
 
 GIT
   remote: https://github.com/tzmfreedom/json_refs
-  revision: e32deb073ce9aef39bdd63556bffd7fe7c2a803d
+  revision: 131b11294fd6af9c428171f38516e6222a58c874
-  ref: e32deb0
+  ref: 131b11294fd6af9c428171f38516e6222a58c874
   specs:
-    json_refs (0.1.2)
+    json_refs (0.1.6)
       hana
 
 GEM
@@ -250,7 +250,7 @@ GEM
       activerecord (>= 5.0, < 7)
       ruby2ruby (~> 2.4)
       ruby_parser (~> 3.10)
-    hana (1.3.6)
+    hana (1.3.7)
     hashdiff (1.0.1)
     hashie (4.1.0)
     hkdf (0.3.0)

swagger/definitions/index.yml

@@ -23,6 +23,8 @@ contact_inboxes:
   $ref: ./resource/contact_inboxes.yml
 account:
   $ref: ./resource/account.yml
+team:
+  $ref: ./resource/team.yml
 
 # RESPONSE
 
@@ -78,3 +80,8 @@ contact_update:
 ## conversation
 conversation_message_create:
   $ref: ./request/conversation/create_message.yml
+
+# Team request Payload
+
+team_create_update_payload:
+  $ref: ./request/team/create_update_payload.yml

swagger/definitions/request/team/create_update_payload.yml

@@ -0,0 +1,11 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the team
+  description:
+    type: string
+    description: The description of the team
+  allow_auto_assign:
+    type: boolean
+    description: If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team

swagger/definitions/resource/team.yml

@@ -0,0 +1,20 @@
+type: object
+properties:
+  id:
+    type: number
+    description: The id of the team
+  name:
+    type: string
+    description: The name of the team
+  description:
+    type: string
+    description: The description about the team
+  allow_auto_assign:
+    type: boolean
+    description: If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team
+  account_id:
+    type: number
+    description: The id of the account with the team is a part of
+  is_member:
+    type: boolean
+    description: This field shows whether the current user is a part of the team

swagger/index.html

@@ -5,7 +5,6 @@
     <!-- needed for adaptive design -->
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
     <!--
     ReDoc doesn't change outer page styles
     -->
@@ -13,6 +12,7 @@
       body {
         margin: 0;
         padding: 0;
+        font-family:  'Helvetica Neue', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', sans-serif;
       }
     </style>
   </head>

swagger/index.yml

@@ -1,4 +1,4 @@
-swagger: 2.0
+swagger: "2.0"
 info:
   description: This is the API documentation for Chatwoot server.
   version: 1.0.0
@@ -40,3 +40,5 @@ paths:
   $ref: ./paths/index.yml
 definitions:
   $ref: ./definitions/index.yml
+parameters:
+  $ref: ./parameters/index.yml

swagger/parameters/account_id.yml

@@ -0,0 +1,6 @@
+in: path
+name: account_id
+schema:
+  type: integer
+required: true
+description: Numeric ID of the account

swagger/parameters/index.yml

@@ -0,0 +1,5 @@
+account_id:
+  $ref: ./account_id.yml
+
+team_id:
+  $ref: ./team_id.yml

swagger/parameters/team_id.yml

@@ -0,0 +1,6 @@
+in: path
+name: id
+schema:
+  type: integer
+required: true
+description: The id of the team to be updated

swagger/paths/conversation/assignments.yml

@@ -3,7 +3,7 @@ post:
     - ConversationAssignment
   operationId: conversationAssignment
   summary: Assign Conversation
-  description: Assign a conversation to an agent
+  description: Assign a conversation to an agent or a team
   parameters:
     - name: id
       in: path
@@ -18,6 +18,10 @@ post:
         properties:
           assignee_id:
             type: number
+            description: Id of the assignee user
+          team_id:
+            type: number
+            description: Id of the team. If the assignee_id is present, this param would be ignored
   responses:
     200:
       description: Success

swagger/paths/index.yml

@@ -52,3 +52,23 @@
 # Profile
 /profile:
   $ref: ./profile/index.yml
+
+# Teams
+/accounts/{account_id}/teams:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: ./teams/index.yml
+  post:
+    $ref: ./teams/create.yml
+
+/accounts/{account_id}/teams/{id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/team_id'
+  get:
+    $ref: './teams/show.yml'
+  patch:
+    $ref: ./teams/update.yml
+  delete:
+    $ref: ./teams/delete.yml

swagger/paths/teams/create.yml

@@ -0,0 +1,19 @@
+tags:
+  - Teams
+operationId: create-a-team
+summary: Create a team
+description: Create a team in the account
+parameters:
+  - $ref: '#/parameters/account_id'
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/team_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/team'
+  401:
+    description: Unauthorized

swagger/paths/teams/delete.yml

@@ -0,0 +1,12 @@
+tags:
+  - Teams
+operationId: delete-a-team,
+summary: Delete a team
+description: Delete a team from the account
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The team does not exist in the account

swagger/paths/teams/index.yml

@@ -0,0 +1,14 @@
+tags:
+  - Teams
+operationId: list-all-teams
+summary: List all teams
+description: List all teams available in the current account
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of teams'
+      $ref: '#/definitions/team'
+  401:
+    description: Unauthorized

swagger/paths/teams/show.yml

@@ -0,0 +1,14 @@
+tags:
+  - Teams
+operationId: get-details-of-a-single-team
+summary: Get a team details
+description: Get the details of a team in the account
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/team'
+  401:
+    description: Unauthorized
+  404:
+    description: The given team id does not exist in the account

swagger/paths/teams/update.yml

@@ -0,0 +1,18 @@
+tags:
+  - Teams
+operationId: update-a-team
+summary: Update a team
+description: Update a team's attributes
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/team_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/team'
+  401:
+    description: Unauthorized

swagger/swagger.json

@@ -1,5 +1,5 @@
 {
-  "swagger": 2.0,
+  "swagger": "2.0",
   "info": {
     "description": "This is the API documentation for Chatwoot server.",
     "version": "1.0.0",
@@ -698,7 +698,7 @@
         ],
         "operationId": "conversationAssignment",
         "summary": "Assign Conversation",
-        "description": "Assign a conversation to an agent",
+        "description": "Assign a conversation to an agent or a team",
         "parameters": [
           {
             "name": "id",
@@ -715,7 +715,12 @@
               "type": "object",
               "properties": {
                 "assignee_id": {
-                  "type": "number"
+                  "type": "number",
+                  "description": "Id of the assignee user"
+                },
+                "team_id": {
+                  "type": "number",
+                  "description": "Id of the team. If the assignee_id is present, this param would be ignored"
                 }
               }
             }
@@ -1002,6 +1007,144 @@
           }
         }
       }
+    },
+    "/accounts/{account_id}/teams": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Teams"
+        ],
+        "operationId": "list-all-teams",
+        "summary": "List all teams",
+        "description": "List all teams available in the current account",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/team"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Teams"
+        ],
+        "operationId": "create-a-team",
+        "summary": "Create a team",
+        "description": "Create a team in the account",
+        "parameters": [
+          {
+            "$ref": "#/parameters/account_id"
+          },
+          {
+            "name": "data",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/team_create_update_payload"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/team"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/accounts/{account_id}/teams/{id}": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        },
+        {
+          "$ref": "#/parameters/team_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Teams"
+        ],
+        "operationId": "get-details-of-a-single-team",
+        "summary": "Get a team details",
+        "description": "Get the details of a team in the account",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/team"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "The given team id does not exist in the account"
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Teams"
+        ],
+        "operationId": "update-a-team",
+        "summary": "Update a team",
+        "description": "Update a team's attributes",
+        "parameters": [
+          {
+            "name": "data",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/team_create_update_payload"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/team"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Teams"
+        ],
+        "operationId": "delete-a-tea,",
+        "summary": "Delete a team",
+        "description": "Delete a team from the account",
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "The team does not exist in the account"
+          }
+        }
+      }
     }
   },
   "definitions": {
@@ -1326,6 +1469,35 @@
         }
       }
     },
+    "team": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The id of the team"
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the team"
+        },
+        "description": {
+          "type": "string",
+          "description": "The description about the team"
+        },
+        "allow_auto_assign": {
+          "type": "boolean",
+          "description": "If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team"
+        },
+        "account_id": {
+          "type": "number",
+          "description": "The id of the account with the team is a part of"
+        },
+        "is_member": {
+          "type": "boolean",
+          "description": "This field shows whether the current user is a part of the team"
+        }
+      }
+    },
     "extended_contact": {
       "allOf": [
         {
@@ -1671,6 +1843,43 @@
           "description": "attributes based on your content type"
         }
       }
+    },
+    "team_create_update_payload": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of the team"
+        },
+        "description": {
+          "type": "string",
+          "description": "The description of the team"
+        },
+        "allow_auto_assign": {
+          "type": "boolean",
+          "description": "If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team"
+        }
+      }
+    }
+  },
+  "parameters": {
+    "account_id": {
+      "in": "path",
+      "name": "account_id",
+      "schema": {
+        "type": "integer"
+      },
+      "required": true,
+      "description": "Numeric ID of the account"
+    },
+    "team_id": {
+      "in": "path",
+      "name": "id",
+      "schema": {
+        "type": "integer"
+      },
+      "required": true,
+      "description": "The id of the team to be updated"
     }
   }
 }