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

swagger/paths/conversation/assignments.yml

@@ -1,33 +1,27 @@
-post:
-  tags:
-    - ConversationAssignment
-  operationId: conversationAssignment
-  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
-      required: true
-      schema:
-        type: object
-        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
-      schema:
-        $ref: '#/definitions/user'
-    404:
-      description: Conversation not found
-    403:
-      description: Access denied
+tags:
+  - Conversation Assignment
+operationId: assign-a-conversation
+summary: Assign Conversation
+description: Assign a conversation to an agent or a team
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      type: object
+      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
+    schema:
+      $ref: '#/definitions/user'
+  404:
+    description: Conversation not found
+  401:
+    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,35 +1,29 @@
-post:
-  tags:
-    - Conversation
-  operationId: conversationToggleStatus
-  summary: Toggle Status
-  description: Toggles the status of the conversation between open and resolved
-  security:
-    - userApiKey: []
-    - agentBotApiKey: []
-  parameters:
-    - name: id
-      in: path
-      type: number
-      description: ID of the conversation
-      required: true
-    - name: data
-      in: body
-      required: true
-      schema:
-        type: object
-        properties:
-          status:
-            type: string
-            enum: ["open", "resolved", "bot"]
-            required: true
-            description: The status of the conversation
-  responses:
-    200:
-      description: Success
-      schema:
-        $ref: '#/definitions/conversation_status_toggle'
-    404:
-      description: Conversation not found
-    403:
-      description: Access denied
+tags:
+  - Conversation
+operationId: toggle-status-of-a-conversation
+summary: Toggle Status
+description: Toggles the status of the conversation between open and resolved
+security:
+  - userApiKey: []
+  - agentBotApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ["open", "resolved", "bot"]
+          required: true
+          description: The status of the conversation
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/conversation_status_toggle'
+  404:
+    description: Conversation not found
+  401:
+    description: Unauthorized

swagger/paths/index.yml

@@ -16,21 +16,58 @@
 
 # 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/{id}/toggle_status:
-  $ref: ./conversation/toggle_status.yml
+
+/accounts/{account_id}/conversations/{converstion_id}:
+  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:
-  $ref: ./conversation/messages/index_create.yml
+/accounts/{account_id}/conversations/{converstion_id}/messages:
+  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:
-  $ref: ./conversation/labels.yml
+/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}:
+  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:
-  $ref: ./conversation/assignments.yml
+
+/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
 /accounts/{account_id}/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: