Chore: Update Swagger API docs (#608)

swagger/definitions/index.yml

@@ -15,7 +15,8 @@ message:
   $ref: ./resource/message.yml
 user:
   $ref: ./resource/user.yml
-
+inbox:
+  $ref: ./resource/inbox.yml
 # RESPONSE
 
 ## contact

swagger/definitions/request/conversation/create_message.yml

@@ -2,9 +2,12 @@ type: object
 properties:
   conversation_id:
     type: number
+    description: ID of the conversation
+    required: true
   message:
     type: string
+    description: The content of the message
+    required: true
   private:
     type: boolean
-  fb_id:
+    description: Flag to identify if it is a private note
-    type: number

swagger/definitions/resource/contact.yml

@@ -2,11 +2,16 @@ type: object
 properties:
   email:
     type: string
+    description: Email address of the contact
   name:
     type: string
+    description: The name of the contact
   phone_number:
     type: string
+    description: Phone number of the contact
   thumbnail:
     type: string
+    description: Avatar URL of the contact
   additional_attributes:
     type: object
+    description: The object containing additional attributes related to the contact

swagger/definitions/resource/conversation.yml

@@ -1,19 +1,27 @@
 type: object
 properties:
+  id:
+    type: number
+    description: ID of the conversation
   messages:
     type: array
-    items:
-      type: object
   inbox_id:
     type: number
+    description: ID of the inbox
   status:
     type: string
-    enum: ['open', 'resolved']
+    enum: ['open', 'resolved', 'bot']
+    description: The status of the conversation
   timestamp:
     type: string
+    description: The time at which conversation was created
   user_last_seen_at:
     type: string
   agent_last_seen_at:
     type: agent_last_seen_at
   unread_count:
     type: number
+    description: The number of unread messages
+  additional_attributes:
+    type: object
+    description: The object containing additional attributes related to the conversation

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

@@ -8,11 +8,15 @@ properties:
         properties:
           id:
             type: number
+            description: ID fo the sender
           name:
             type: string
+            description: The name of the sender
           thumbnail:
             type: string
+            description: Avatar URL of the contact
           channel:
             type: string
+            description: Channel Type
       assignee:
         $ref: '#/definitions/user'

swagger/definitions/resource/extension/contact/show.yml

@@ -2,6 +2,8 @@ type: object
 properties:
   id:
     type: number
+    description: Id of the user
   availability_status:
     type: string
-    enum: ['online', 'offline']
+    enum: ['online', 'offline']
+    description: Availability status of the user

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

@@ -2,6 +2,6 @@ type: object
 properties:
   payload:
     type: array
-    description: 'array of labels'
+    description: Array of labels
     items:
       type: string

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

@@ -1,19 +1,5 @@
 type: object
-properties:
+allOf:
-  meta:
+  - $ref: '#/definitions/generic_id'
-    type: object
+  - $ref: '#/definitions/conversation'
-    properties:
+  - $ref: '../contact/conversation.yml'
-      labels:
-        type: array
-        items:
-          type: string
-      additional_attributes:
-        type: object
-      contact_id:
-        type: number
-  payload:
-    type: array
-    description: 'array of messages'
-    items:
-      allOf:
-        - $ref: '#/definitions/extended_message'

swagger/definitions/resource/inbox.yml

@@ -0,0 +1,20 @@
+type: object
+properties:
+  id:
+    type: number
+    description: ID of the inbox
+  channel_type:
+    type: string
+    description: The type of the inbox
+  avatar_url:
+    type: string
+    description: The avatar image of the inbox
+  widget_color:
+    type: string
+    description: Widget Color used for customization of the widget
+  website_token:
+    type: string
+    description: Website Token
+  enable_auto_assignment:
+    type: boolean
+    description: The flag which shows whether Auto Assignment is enabled or not

swagger/definitions/resource/message.yml

@@ -2,15 +2,23 @@ type: object
 properties:
   content:
     type: string
-  inbox_id:
+    description: The text content of the message
-    type: number
-  conversation_id:
-    type: number
   message_type:
     type: string
+    enum: ["incoming", "outgoing", "activity", "template"]
+    description: The type of the message
   created_at:
     type: integer
+    description: The time at which message was created
   private:
     type: boolean
+    description: The flags which shows whether the message is private or not
   attachment:
     type: object
+    description: The file object attached to the image
+  sender:
+    type: object
+    description: User/Agent/AgentBot object
+  conversation_id:
+    type: number
+    description: ID of the conversation

swagger/index.yml

@@ -1,6 +1,6 @@
 swagger: 2.0
 info:
-  description: This is the api documentation for Chatwoot server.
+  description: This is the API documentation for Chatwoot server.
   version: 1.0.0
   title: Chatwoot
   termsOfService:	https://www.chatwoot.com/terms-of-service/
@@ -9,8 +9,15 @@ info:
   license:
     name: MIT License
     url: https://opensource.org/licenses/MIT
-  host: app.chatwoot.com
+host: app.chatwoot.com
-  basePath: /api/v1/
+basePath: /api/v1/
+schemes:
+  - https
+produces:
+- application/json; charset=utf-8
+consumes:
+- application/json; charset=utf-8
+
 paths:
   $ref: ./paths/index.yml
 definitions:

swagger/paths/conversation/assignments.yml

@@ -1,6 +1,6 @@
 post:
   tags:
-    - Conversation
+    - ConversationAssignment
   operationId: conversationAssignment
   summary: Assign Conversation
   description: Assign a conversation to an agent
@@ -19,7 +19,7 @@ post:
           assignee_id:
             type: number
   responses:
-    204:
+    200:
       description: Success
       schema:
         $ref: '#/definitions/user'

swagger/paths/conversation/labels.yml

@@ -1,6 +1,6 @@
 get:
   tags:
-    - Conversation
+    - ConversationLabels
   operationId: conversationLabelsList
   summary: List Labels
   description: Lists all the labels of a conversation
@@ -8,7 +8,7 @@ get:
     - name: id
       in: path
       type: number
-      description: id of the conversation
+      description: ID of the conversation
       required: true
   responses:
     200:
@@ -22,7 +22,7 @@ get:
 
 post:
   tags:
-    - Conversation
+    - ConversationLabels
   operationId: conversationAddLabels
   summary: Add Labels
   description: Creates new labels and associates it with the conversation
@@ -30,7 +30,7 @@ post:
     - name: id
       in: path
       type: number
-      description: id of the conversation
+      description: ID of the conversation
       required: true
     - name: data
       in: body
@@ -40,11 +40,11 @@ post:
         properties:
           labels:
             type: array
-            description: 'array of labels'
+            description: 'Array of labels'
             properties:
               type: string
   responses:
-    204:
+    200:
       description: Success
       schema:
         $ref: '#/definitions/conversation_labels'

swagger/paths/conversation/list.yml

@@ -5,9 +5,29 @@ get:
   description: List all the conversations with pagination
   summary: Conversations List
   parameters:
-    - name: query_hash
+    - name: assignee_type
       in: query
       type: string
+      enum: ['me', 'unassigned', 'all']
+      required: true
+    - name: status
+      in: query
+      type: string
+      enum: ['open', 'resolved', 'bot']
+      required: true
+    - name: page
+      in: query
+      type: integer
+      required: true
+    - name: inbox_id
+      in: query
+      type: integer
+    - name: labels
+      in: query
+      type: array
+      items:
+        type: string
+
   responses:
     200:
       description: Success

swagger/paths/conversation/messages.yml

@@ -1,28 +0,0 @@
-post:
-  tags:
-    - Conversation
-  operationId: conversationNewMessage
-  summary: Create New Message
-  description: All the agent replies are created as new messages through this endpoint
-  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:
-    204:
-      description: Success
-      schema:
-        allOf:
-          - $ref: '#/definitions/generic_id'
-          - $ref: '#/definitions/message'
-    404:
-      description: Conversation not found
-    403:
-      description: Access denied

swagger/paths/conversation/messages/index_create.yml

@@ -0,0 +1,54 @@
+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
+  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/toggle_status.yml

@@ -8,10 +8,21 @@ post:
     - name: id
       in: path
       type: number
-      description: id of the conversation
+      description: ID of the conversation
       required: true
+    - name: data
+      in: body
+      required: true
+      schema:
+        type: object
+        properties:
+          status:
+            type: string
+            enum: ["open", "resolved"]
+            required: true
+            description: The status of the conversation
   responses:
-    204:
+    200:
       description: Success
       schema:
         $ref: '#/definitions/conversation_status_toggle'

swagger/paths/inboxes/index.yml

@@ -0,0 +1,17 @@
+get:
+  tags:
+    - Inbox
+  operationId: listAllInboxes
+  summary: List all inboxes
+  description: List all inboxes available in the current account
+  responses:
+    200:
+      description: Success
+      schema:
+        type: array
+        description: 'Array of inboxes'
+        $ref: '#/definitions/inbox'
+    404:
+      description: Inbox not found
+    403:
+      description: Access denied

swagger/paths/inboxes/update.yml

@@ -0,0 +1,33 @@
+patch:
+  tags:
+    - Inbox
+  operationId: disableAutoAssignment
+  summary: Disable auto assignment
+  description: Disable Auto Assignment for an inbox
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: ID of the inbox
+      required: true
+    - name: data
+      in: body
+      required: true
+      schema:
+        type: object
+        properties:
+          enable_auto_assignment:
+            type: boolean
+            required: true
+            description: 'Enable Auto Assignment'
+  responses:
+    200:
+      description: Success
+      schema:
+        type: object
+        description: 'Updated inbox object'
+        $ref: '#/definitions/inbox'
+    404:
+      description: Inbox not found
+    403:
+      description: Access denied

swagger/paths/index.yml

@@ -1,23 +1,37 @@
-# Contacts
+# Widget
-/contacts:
+/account/{account_id}/widget/inboxes:
-  $ref: ./contact/list_create.yml
+  $ref: ./widget/inboxes/create.yml
-/contacts/{id}:
+/account/{account_id}/widget/inboxes/${id}:
-  $ref: ./contact/crud.yml
+  $ref: ./widget/inboxes/update.yml
-/contacts/{id}/conversations:
+
-  $ref: ./contact/conversations.yml
+# Inboxes
+/account/{account_id}/inboxes:
+  $ref: ./inboxes/index.yml
+/account/{account_id}/inboxes/{id}:
+  $ref: ./inboxes/update.yml
 
 # Conversations
-/conversations:
+/account/{account_id}/conversations:
   $ref: ./conversation/list.yml
-/conversations/{id}:
+/account/{account_id}/conversations/{id}:
   $ref: ./conversation/crud.yml
-/conversations/{id}/toggle_status:
+/account/{account_id}/conversations/{id}/toggle_status:
   $ref: ./conversation/toggle_status.yml
-/conversations/{id}/update_last_seen:
+
-  $ref: ./conversation/update_last_seen.yml
+# Messages
-/conversations/{id}/labels:
+/account/{account_id}/conversations/{id}/messages:
+  $ref: ./conversation/messages/index_create.yml
+
+/account/{account_id}/conversations/{id}/labels:
   $ref: ./conversation/labels.yml
-/conversations/{id}/assignments:
+
+/account/{account_id}/conversations/{id}/assignments:
   $ref: ./conversation/assignments.yml
-/conversations/{id}/messages:
+
-  $ref: ./conversation/messages.yml
+# Contacts
+/account/{account_id}/contacts:
+  $ref: ./contact/list_create.yml
+/account/{account_id}/contacts/{id}:
+  $ref: ./contact/crud.yml
+/account/{account_id}/contacts/{id}/conversations:
+  $ref: ./contact/conversations.yml

swagger/paths/widget/inboxes/create.yml

@@ -0,0 +1,34 @@
+post:
+  tags:
+    - Widget
+  operationId: widgetInboxCreation
+  summary: Create a website inbox
+  description: You can create more than one website inbox in each account
+  parameters:
+    - name: data
+      in: body
+      required: true
+      schema:
+        type: object
+        properties:
+          website:
+            type: object
+            properties:
+              website_name:
+                type: string
+                description: The name of the inbox
+              website_url:
+                type: string
+                description: URL at which the widget will be loaded
+              widget_color:
+                type: string
+                description: A Hex-color string used to customize the widget
+  responses:
+    200:
+      description: Success
+      schema:
+        $ref: '#/definitions/inbox'
+    404:
+      description: Inbox not found
+    403:
+      description: Access denied

swagger/paths/widget/inboxes/update.yml

@@ -0,0 +1,28 @@
+patch:
+  tags:
+    - Widget
+  operationId: widgetInboxUpdate
+  summary: Update a website inbox
+  description: Update widget color of an inbox
+  parameters:
+    - name: data
+      in: body
+      required: true
+      schema:
+        type: object
+        properties:
+          website:
+            type: object
+            properties:
+              widget_color:
+                type: string
+                description: A Hex-color string used to customize the widget
+  responses:
+    200:
+      description: Success
+      schema:
+        $ref: '#/definitions/inbox'
+    404:
+      description: Inbox not found
+    403:
+      description: Access denied