chore: Add Message API, cleanup conversation_id param (#2249)

swagger/parameters/account_id.yml

@@ -3,4 +3,4 @@ name: account_id
 schema:
   type: integer
 required: true
-description: Numeric ID of the account
+description: The numeric ID of the account

swagger/parameters/conversation_id.yml

@@ -0,0 +1,6 @@
+in: path
+name: conversation_id
+schema:
+  type: integer
+required: true
+description: The numeric ID of the conversation

swagger/parameters/index.yml

@@ -3,3 +3,9 @@ account_id:
 
 team_id:
   $ref: ./team_id.yml
+
+conversation_id:
+  $ref: ./conversation_id.yml
+
+message_id:
+  $ref: ./message_id.yml

swagger/parameters/message_id.yml

@@ -0,0 +1,6 @@
+in: path
+name: message_id
+schema:
+  type: integer
+required: true
+description: The numeric ID of the message

swagger/paths/conversation/assignments.yml

@@ -1,15 +1,9 @@
-post:
+tags:
-  tags:
+  - Conversation Assignment
-    - ConversationAssignment
+operationId: assign-a-conversation
-  operationId: conversationAssignment
+summary: Assign Conversation
-  summary: Assign Conversation
+description: Assign a conversation to an agent or a team
-  description: Assign a conversation to an agent or a team
+parameters:
-  parameters:
-    - name: id
-      in: path
-      type: number
-      description: id of the conversation
-      required: true
   - name: data
     in: body
     required: true
@@ -22,12 +16,12 @@ post:
         team_id:
           type: number
           description: Id of the team. If the assignee_id is present, this param would be ignored
-  responses:
+responses:
   200:
     description: Success
     schema:
       $ref: '#/definitions/user'
   404:
     description: Conversation not found
-    403:
+  401:
-      description: Access denied
+    description: Unauthorized

swagger/paths/conversation/crud.yml

@@ -1,21 +0,0 @@
-get:
-  tags:
-    - Conversation
-  operationId: conversationDetails
-  summary: Conversation Details
-  description: Get all details regarding a conversation with all messages in the conversation
-  parameters:
-    - name: id
-      in: path
-      type: number
-      description: ID of Conversation
-      required: true
-  responses:
-    200:
-      description: Success
-      schema:
-        $ref: '#/definitions/conversation_show'
-    404:
-      description: Conversation not found
-    403:
-      description: Access denied

swagger/paths/conversation/index_or_create.yml

@@ -5,6 +5,7 @@ get:
   description: List all the conversations with pagination
   summary: Conversations List
   parameters:
+    - $ref: '#/parameters/account_id'
     - name: assignee_type
       in: query
       type: string
@@ -68,6 +69,7 @@ get:
       type: array
       items:
         type: string
+    - $ref: '#/parameters/account_id'
 
   responses:
     200:
@@ -91,6 +93,7 @@ post:
     - userApiKey: []
     - agentBotApiKey: []
   parameters:
+    - $ref: '#/parameters/account_id'
     - name: data
       in: body
       required: true

swagger/paths/conversation/labels.yml

@@ -1,54 +0,0 @@
-get:
-  tags:
-    - ConversationLabels
-  operationId: conversationLabelsList
-  summary: List Labels
-  description: Lists all the labels of a conversation
-  parameters:
-    - name: id
-      in: path
-      type: number
-      description: ID of the conversation
-      required: true
-  responses:
-    200:
-      description: Success
-      schema:
-        $ref: '#/definitions/conversation_labels'
-    404:
-      description: Conversation not found
-    403:
-      description: Access denied
-
-post:
-  tags:
-    - ConversationLabels
-  operationId: conversationAddLabels
-  summary: Add Labels
-  description: Creates new labels and associates it with the conversation
-  parameters:
-    - name: id
-      in: path
-      type: number
-      description: ID of the conversation
-      required: true
-    - name: data
-      in: body
-      required: true
-      schema:
-        type: object
-        properties:
-          labels:
-            type: array
-            description: 'Array of labels'
-            properties:
-              type: string
-  responses:
-    200:
-      description: Success
-      schema:
-        $ref: '#/definitions/conversation_labels'
-    404:
-      description: Conversation not found
-    403:
-      description: Access denied

swagger/paths/conversation/labels/create.yml

@@ -0,0 +1,26 @@
+tags:
+  - Conversation Labels
+operationId: conversation-add-labels
+summary: Add Labels
+description: Add labels to a conversation. Note that this API would overwrite the existing list of labels associated to the conversation.
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      type: object
+      properties:
+        labels:
+          type: array
+          description: Array of labels (comma-separated strings)
+          properties:
+            type: string
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/conversation_labels'
+  404:
+    description: Conversation not found
+  401:
+    description: Unauthorized

swagger/paths/conversation/labels/index.yml

@@ -0,0 +1,14 @@
+tags:
+  - Conversation Labels
+operationId: list-all-labels-of-a-conversation
+summary: List Labels
+description: Lists all the labels of a conversation
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/conversation_labels'
+  404:
+    description: Conversation not found
+  401:
+    description: Unauthorized

swagger/paths/conversation/messages/create.yml

@@ -0,0 +1,25 @@
+tags:
+  - Messages
+operationId: create-a-new-message-in-a-conversation
+summary: Create New Message
+description: Create a new message in the conversation
+security:
+  - userApiKey: []
+  - agentBotApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/conversation_message_create'
+responses:
+  200:
+    description: Success
+    schema:
+      allOf:
+        - $ref: '#/definitions/generic_id'
+        - $ref: '#/definitions/message'
+  404:
+    description: Conversation not found
+  403:
+    description: Access denied

swagger/paths/conversation/messages/delete.yml

@@ -0,0 +1,12 @@
+tags:
+  - Messages
+operationId: delete-a-message
+summary: Delete a message
+description: Delete a message and it's attachments from the conversation.
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The message or conversation does not exist in the account

swagger/paths/conversation/messages/index.yml

@@ -0,0 +1,18 @@
+tags:
+  - Messages
+operationId: list-all-messages
+summary: Get messages
+description: List all messages of a conversation
+responses:
+  200:
+    description: Success
+    type: array
+    description: Array of messages
+    schema:
+      allOf:
+        - $ref: '#/definitions/generic_id'
+        - $ref: '#/definitions/message'
+  404:
+    description: Conversation not found
+  401:
+    description: Unauthorized

swagger/paths/conversation/messages/index_create.yml

@@ -1,57 +0,0 @@
-get:
-  tags:
-    - Messages
-  operationId: listAllMessages
-  summary: Get messages
-  description: List all messages of a conversation
-  parameters:
-    - name: id
-      in: path
-      type: number
-      description: ID of the conversation
-      required: true
-  responses:
-    200:
-      description: Success
-      type: array
-      description: Array of messages
-      schema:
-        allOf:
-          - $ref: '#/definitions/generic_id'
-          - $ref: '#/definitions/message'
-    404:
-      description: Conversation not found
-    403:
-      description: Access denied
-
-post:
-  tags:
-    - Messages
-  operationId: conversationNewMessage
-  summary: Create New Message
-  description: All the agent replies are created as new messages through this endpoint
-  security:
-    - userApiKey: []
-    - agentBotApiKey: []
-  parameters:
-    - name: id
-      in: path
-      type: number
-      description: ID of the conversation
-      required: true
-    - name: data
-      in: body
-      required: true
-      schema:
-        $ref: '#/definitions/conversation_message_create'
-  responses:
-    200:
-      description: Success
-      schema:
-        allOf:
-          - $ref: '#/definitions/generic_id'
-          - $ref: '#/definitions/message'
-    404:
-      description: Conversation not found
-    403:
-      description: Access denied

swagger/paths/conversation/show.yml

@@ -0,0 +1,14 @@
+tags:
+  - Conversation
+operationId: get-details-of-a-conversation
+summary: Conversation Details
+description: Get all details regarding a conversation with all messages in the conversation
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/conversation_show'
+  404:
+    description: Conversation not found
+  403:
+    description: Access denied

swagger/paths/conversation/toggle_status.yml

@@ -1,18 +1,12 @@
-post:
+tags:
-  tags:
   - Conversation
-  operationId: conversationToggleStatus
+operationId: toggle-status-of-a-conversation
-  summary: Toggle Status
+summary: Toggle Status
-  description: Toggles the status of the conversation between open and resolved
+description: Toggles the status of the conversation between open and resolved
-  security:
+security:
   - userApiKey: []
   - agentBotApiKey: []
-  parameters:
+parameters:
-    - name: id
-      in: path
-      type: number
-      description: ID of the conversation
-      required: true
   - name: data
     in: body
     required: true
@@ -24,12 +18,12 @@ post:
           enum: ["open", "resolved", "bot"]
           required: true
           description: The status of the conversation
-  responses:
+responses:
   200:
     description: Success
     schema:
       $ref: '#/definitions/conversation_status_toggle'
   404:
     description: Conversation not found
-    403:
+  401:
-      description: Access denied
+    description: Unauthorized

swagger/paths/index.yml

@@ -16,20 +16,57 @@
 
 # Conversations
 /accounts/{account_id}/conversations:
+  parameters:
+    - $ref: '#/parameters/account_id'
   $ref: ./conversation/index_or_create.yml
-/accounts/{account_id}/conversations/{id}:
+
-  $ref: ./conversation/crud.yml
+/accounts/{account_id}/conversations/{converstion_id}:
-/accounts/{account_id}/conversations/{id}/toggle_status:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+  get:
+    $ref: ./conversation/show.yml
+
+/accounts/{account_id}/conversations/{conversation_id}/toggle_status:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+  post:
     $ref: ./conversation/toggle_status.yml
 
 # Messages
-/accounts/{account_id}/conversations/{id}/messages:
+/accounts/{account_id}/conversations/{converstion_id}/messages:
-  $ref: ./conversation/messages/index_create.yml
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+  get:
+    $ref: ./conversation/messages/index.yml
+  post:
+    $ref: ./conversation/messages/create.yml
 
-/accounts/{account_id}/conversations/{id}/labels:
+/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}:
-  $ref: ./conversation/labels.yml
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+    - $ref: '#/parameters/message_id'
+  delete:
+    $ref: ./conversation/messages/delete.yml
 
-/accounts/{account_id}/conversations/{id}/assignments:
+
+/accounts/{account_id}/conversations/{conversation_id}/labels:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+  get:
+    $ref: ./conversation/labels/index.yml
+  post:
+    $ref: ./conversation/labels/create.yml
+
+/accounts/{account_id}/conversations/{conversation_id}/assignments:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+  post:
     $ref: ./conversation/assignments.yml
 
 # Contacts

swagger/paths/teams/delete.yml

@@ -1,6 +1,6 @@
 tags:
   - Teams
-operationId: delete-a-team,
+operationId: delete-a-team
 summary: Delete a team
 description: Delete a team from the account
 responses:

swagger/swagger.json

@@ -329,6 +329,9 @@
             "items": {
               "type": "string"
             }
+          },
+          {
+            "$ref": "#/parameters/account_id"
           }
         ],
         "responses": {
@@ -367,6 +370,9 @@
           }
         ],
         "parameters": [
+          {
+            "$ref": "#/parameters/account_id"
+          },
           {
             "name": "data",
             "in": "body",
@@ -413,23 +419,22 @@
         }
       }
     },
-    "/accounts/{account_id}/conversations/{id}": {
+    "/accounts/{account_id}/conversations/{converstion_id}": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        },
+        {
+          "$ref": "#/parameters/conversation_id"
+        }
+      ],
       "get": {
         "tags": [
           "Conversation"
         ],
-        "operationId": "conversationDetails",
+        "operationId": "get-details-of-a-conversation",
         "summary": "Conversation Details",
         "description": "Get all details regarding a conversation with all messages in the conversation",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "type": "number",
-            "description": "ID of Conversation",
-            "required": true
-          }
-        ],
         "responses": {
           "200": {
             "description": "Success",
@@ -446,12 +451,20 @@
         }
       }
     },
-    "/accounts/{account_id}/conversations/{id}/toggle_status": {
+    "/accounts/{account_id}/conversations/{conversation_id}/toggle_status": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        },
+        {
+          "$ref": "#/parameters/conversation_id"
+        }
+      ],
       "post": {
         "tags": [
           "Conversation"
         ],
-        "operationId": "conversationToggleStatus",
+        "operationId": "toggle-status-of-a-conversation",
         "summary": "Toggle Status",
         "description": "Toggles the status of the conversation between open and resolved",
         "security": [
@@ -467,13 +480,6 @@
           }
         ],
         "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "type": "number",
-            "description": "ID of the conversation",
-            "required": true
-          },
           {
             "name": "data",
             "in": "body",
@@ -505,29 +511,28 @@
           "404": {
             "description": "Conversation not found"
           },
-          "403": {
+          "401": {
-            "description": "Access denied"
+            "description": "Unauthorized"
           }
         }
       }
     },
-    "/accounts/{account_id}/conversations/{id}/messages": {
+    "/accounts/{account_id}/conversations/{converstion_id}/messages": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        },
+        {
+          "$ref": "#/parameters/conversation_id"
+        }
+      ],
       "get": {
         "tags": [
           "Messages"
         ],
-        "operationId": "listAllMessages",
+        "operationId": "list-all-messages",
         "summary": "Get messages",
         "description": "List all messages of a conversation",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "type": "number",
-            "description": "ID of the conversation",
-            "required": true
-          }
-        ],
         "responses": {
           "200": {
             "description": "Array of messages",
@@ -546,8 +551,8 @@
           "404": {
             "description": "Conversation not found"
           },
-          "403": {
+          "401": {
-            "description": "Access denied"
+            "description": "Unauthorized"
           }
         }
       },
@@ -555,9 +560,9 @@
         "tags": [
           "Messages"
         ],
-        "operationId": "conversationNewMessage",
+        "operationId": "create-a-new-message-in-a-conversation",
         "summary": "Create New Message",
-        "description": "All the agent replies are created as new messages through this endpoint",
+        "description": "Create a new message in the conversation",
         "security": [
           {
             "userApiKey": [
@@ -571,13 +576,6 @@
           }
         ],
         "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "type": "number",
-            "description": "ID of the conversation",
-            "required": true
-          },
           {
             "name": "data",
             "in": "body",
@@ -610,23 +608,54 @@
         }
       }
     },
-    "/accounts/{account_id}/conversations/{id}/labels": {
+    "/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}": {
-      "get": {
-        "tags": [
-          "ConversationLabels"
-        ],
-        "operationId": "conversationLabelsList",
-        "summary": "List Labels",
-        "description": "Lists all the labels of a conversation",
       "parameters": [
         {
-            "name": "id",
+          "$ref": "#/parameters/account_id"
-            "in": "path",
+        },
-            "type": "number",
+        {
-            "description": "ID of the conversation",
+          "$ref": "#/parameters/conversation_id"
-            "required": true
+        },
+        {
+          "$ref": "#/parameters/message_id"
         }
       ],
+      "delete": {
+        "tags": [
+          "Messages"
+        ],
+        "operationId": "delete-a-message",
+        "summary": "Delete a message",
+        "description": "Delete a message and it's attachments from the conversation.",
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "The message or conversation does not exist in the account"
+          }
+        }
+      }
+    },
+    "/accounts/{account_id}/conversations/{conversation_id}/labels": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        },
+        {
+          "$ref": "#/parameters/conversation_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Conversation Labels"
+        ],
+        "operationId": "list-all-labels-of-a-conversation",
+        "summary": "List Labels",
+        "description": "Lists all the labels of a conversation",
         "responses": {
           "200": {
             "description": "Success",
@@ -637,26 +666,19 @@
           "404": {
             "description": "Conversation not found"
           },
-          "403": {
+          "401": {
-            "description": "Access denied"
+            "description": "Unauthorized"
           }
         }
       },
       "post": {
         "tags": [
-          "ConversationLabels"
+          "Conversation Labels"
         ],
-        "operationId": "conversationAddLabels",
+        "operationId": "conversation-add-labels",
         "summary": "Add Labels",
-        "description": "Creates new labels and associates it with the conversation",
+        "description": "Add labels to a conversation. Note that this API would overwrite the existing list of labels associated to the conversation.",
         "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "type": "number",
-            "description": "ID of the conversation",
-            "required": true
-          },
           {
             "name": "data",
             "in": "body",
@@ -666,7 +688,7 @@
               "properties": {
                 "labels": {
                   "type": "array",
-                  "description": "Array of labels",
+                  "description": "Array of labels (comma-separated strings)",
                   "properties": {
                     "type": "string"
                   }
@@ -685,28 +707,29 @@
           "404": {
             "description": "Conversation not found"
           },
-          "403": {
+          "401": {
-            "description": "Access denied"
+            "description": "Unauthorized"
           }
         }
       }
     },
-    "/accounts/{account_id}/conversations/{id}/assignments": {
+    "/accounts/{account_id}/conversations/{conversation_id}/assignments": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        },
+        {
+          "$ref": "#/parameters/conversation_id"
+        }
+      ],
       "post": {
         "tags": [
-          "ConversationAssignment"
+          "Conversation Assignment"
         ],
-        "operationId": "conversationAssignment",
+        "operationId": "assign-a-conversation",
         "summary": "Assign Conversation",
         "description": "Assign a conversation to an agent or a team",
         "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "type": "number",
-            "description": "id of the conversation",
-            "required": true
-          },
           {
             "name": "data",
             "in": "body",
@@ -736,8 +759,8 @@
           "404": {
             "description": "Conversation not found"
           },
-          "403": {
+          "401": {
-            "description": "Access denied"
+            "description": "Unauthorized"
           }
         }
       }
@@ -1130,7 +1153,7 @@
         "tags": [
           "Teams"
         ],
-        "operationId": "delete-a-tea,",
+        "operationId": "delete-a-team",
         "summary": "Delete a team",
         "description": "Delete a team from the account",
         "responses": {
@@ -1870,7 +1893,7 @@
         "type": "integer"
       },
       "required": true,
-      "description": "Numeric ID of the account"
+      "description": "The numeric ID of the account"
     },
     "team_id": {
       "in": "path",
@@ -1880,6 +1903,24 @@
       },
       "required": true,
       "description": "The id of the team to be updated"
+    },
+    "conversation_id": {
+      "in": "path",
+      "name": "conversation_id",
+      "schema": {
+        "type": "integer"
+      },
+      "required": true,
+      "description": "The numeric ID of the conversation"
+    },
+    "message_id": {
+      "in": "path",
+      "name": "message_id",
+      "schema": {
+        "type": "integer"
+      },
+      "required": true,
+      "description": "The numeric ID of the message"
     }
   }
 }