chore: Add documentation for APIs (#2248)

swagger/definitions/index.yml

@@ -21,6 +21,8 @@ agent_bot:
   $ref: ./resource/agent_bot.yml
 contact_inboxes:
   $ref: ./resource/contact_inboxes.yml
+contactable_inboxes:
+  $ref: ./resource/contactable_inboxes.yml
 account:
   $ref: ./resource/account.yml
 team:

swagger/definitions/resource/contactable_inboxes.yml

@@ -0,0 +1,8 @@
+type: object
+properties:
+  source_id:
+    type: string
+    description: Contact Inbox Source Id
+  inbox:
+    type: object
+    $ref: '#/definitions/inbox'

swagger/parameters/index.yml

@@ -4,8 +4,13 @@ account_id:
 team_id:
   $ref: ./team_id.yml
 
+
+source_id:
+  $ref: ./source_id.yml
+
 conversation_id:
   $ref: ./conversation_id.yml
 
 message_id:
   $ref: ./message_id.yml
+

swagger/parameters/source_id.yml

@@ -0,0 +1,2 @@
+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"

swagger/paths/contact_inboxes/create.yml

@@ -15,6 +15,8 @@ post:
             type: number
             description: The id of the inbox
             required: true
+          source_id:
+            $ref: '#/parameters/source_id'
   responses:
     200:
       description: Success

swagger/paths/contactable_inboxes/get.yml

@@ -0,0 +1,17 @@
+get:
+  tags:
+    - Contact
+  operationId: contactableInboxesGet
+  description: Get List of contactable Inboxes
+  summary: Get Contactable Inboxes
+  responses:
+    200:
+      description: Success
+      schema:
+        $ref: '#/definitions/contactable_inboxes'
+    401:
+      description: Authentication error
+      schema:
+        $ref: '#/definitions/bad_request_error'
+    422:
+      description: Incorrect payload

swagger/paths/conversation/index_or_create.yml

@@ -88,7 +88,7 @@ post:
     - Conversation
   operationId: newConversation
   summary: Create New Conversation
-  description: Create conversation
+  description: "Creating a conversation in chatwoot requires a source id. \n\n Learn more about source_id: https://github.com/chatwoot/chatwoot/wiki/Building-on-Top-of-Chatwoot:-Importing-Existing-Contacts-and-Creating-Conversations"
   security:
     - userApiKey: []
     - agentBotApiKey: []
@@ -100,9 +100,14 @@ post:
       schema:
         type: object
         properties:
-          source_id:
+          source_id: 
+            $ref: '#/parameters/source_id'
+          inbox_id:
             type: string
-            description: Contact Source Id
+            description: "Id of inbox in which the conversation is created <br/> Allowed Inbox Types: Website, Phone, Api, Email "
+          contact_id:
+            type: string
+            description: Contact Id for which conversation is created
           additional_attributes:
             type: object
             description: Lets you specify attributes like browser information

swagger/paths/conversation/messages/create_attachment.yml

@@ -0,0 +1,47 @@
+post:
+  tags:
+    - Messages
+  operationId: conversationNewMessageAttachment
+  summary: Create New Message Attachment
+  description: Create an attachment Message
+  consumes:
+    - multipart/form-data
+  security:
+    - userApiKey: []
+    - agentBotApiKey: []
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+      required: true
+    - in: formData
+      name: content
+      type: string
+      description: The content of the message
+      required: true
+    - in: formData
+      name: message_type
+      type: string
+      enum: ['outgoing', 'incoming']
+    - in: formData
+      name: private
+      type: boolean
+      description: Flag to identify if it is a private note
+    - in: formData
+      name: attachments
+      type: array
+      description: The files to be uploaded.
+      items:
+        type: file
+
+
+  responses:
+    200:
+      description: Success
+      schema:
+        allOf:
+          - $ref: '#/definitions/generic_id'
+          - $ref: '#/definitions/message'
+    404:
+      description: Conversation not found
+    403:
+      description: Access denied

swagger/paths/index.yml

@@ -4,7 +4,7 @@
 # Inboxes
 /accounts/{account_id}/inboxes:
   $ref: ./inboxes/index.yml
-/accounts/{account_id}/inboxes:
+/accounts/{account_id}/inboxes/:
   $ref: ./inboxes/create.yml
 /accounts/{account_id}/inboxes/{id}:
   $ref: ./inboxes/update.yml
@@ -35,6 +35,8 @@
     $ref: ./conversation/toggle_status.yml
 
 # Messages
+/accounts/{account_id}/conversations/{id}/messages:
+  $ref: ./conversation/messages/create_attachment.yml
 /accounts/{account_id}/conversations/{converstion_id}/messages:
   parameters:
     - $ref: '#/parameters/account_id'
@@ -84,6 +86,8 @@
 
 /accounts/{account_id}/contacts/{id}/contact_inboxes:
   $ref: ./contact_inboxes/create.yml
+/accounts/{account_id}/contacts/{id}/contactable_inboxes:
+  $ref: ./contactable_inboxes/get.yml
 
 
 # Profile

swagger/swagger.json

@@ -53,6 +53,30 @@
   ],
   "paths": {
     "/accounts/{account_id}/inboxes": {
+      "get": {
+        "tags": [
+          "Inbox"
+        ],
+        "operationId": "listAllInboxes",
+        "summary": "List all inboxes",
+        "description": "List all inboxes available in the current account",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/inbox"
+            }
+          },
+          "404": {
+            "description": "Inbox not found"
+          },
+          "403": {
+            "description": "Access denied"
+          }
+        }
+      }
+    },
+    "/accounts/{account_id}/inboxes/": {
       "post": {
         "tags": [
           "Inbox"
@@ -356,7 +380,7 @@
         ],
         "operationId": "newConversation",
         "summary": "Create New Conversation",
-        "description": "Create conversation",
+        "description": "Creating a conversation in chatwoot requires a source id. \n\n Learn more about source_id: https://github.com/chatwoot/chatwoot/wiki/Building-on-Top-of-Chatwoot:-Importing-Existing-Contacts-and-Creating-Conversations",
         "security": [
           {
             "userApiKey": [
@@ -381,8 +405,15 @@
               "type": "object",
               "properties": {
                 "source_id": {
+                  "$ref": "#/parameters/source_id"
+                },
+                "inbox_id": {
                   "type": "string",
-                  "description": "Contact Source Id"
+                  "description": "Id of inbox in which the conversation is created <br/> Allowed Inbox Types: Website, Phone, Api, Email "
+                },
+                "contact_id": {
+                  "type": "string",
+                  "description": "Contact Id for which conversation is created"
                 },
                 "additional_attributes": {
                   "type": "object",
@@ -517,6 +548,91 @@
         }
       }
     },
+    "/accounts/{account_id}/conversations/{id}/messages": {
+      "post": {
+        "tags": [
+          "Messages"
+        ],
+        "operationId": "conversationNewMessageAttachment",
+        "summary": "Create New Message Attachment",
+        "description": "Create an attachment Message",
+        "consumes": [
+          "multipart/form-data"
+        ],
+        "security": [
+          {
+            "userApiKey": [
+
+            ]
+          },
+          {
+            "agentBotApiKey": [
+
+            ]
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/parameters/account_id"
+          },
+          {
+            "$ref": "#/parameters/conversation_id"
+          },
+          {
+            "in": "formData",
+            "name": "content",
+            "type": "string",
+            "description": "The content of the message",
+            "required": true
+          },
+          {
+            "in": "formData",
+            "name": "message_type",
+            "type": "string",
+            "enum": [
+              "outgoing",
+              "incoming"
+            ]
+          },
+          {
+            "in": "formData",
+            "name": "private",
+            "type": "boolean",
+            "description": "Flag to identify if it is a private note"
+          },
+          {
+            "in": "formData",
+            "name": "attachments",
+            "type": "array",
+            "description": "The files to be uploaded.",
+            "items": {
+              "type": "file"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "allOf": [
+                {
+                  "$ref": "#/definitions/generic_id"
+                },
+                {
+                  "$ref": "#/definitions/message"
+                }
+              ]
+            }
+          },
+          "404": {
+            "description": "Conversation not found"
+          },
+          "403": {
+            "description": "Access denied"
+          }
+        }
+      }
+    },
     "/accounts/{account_id}/conversations/{converstion_id}/messages": {
       "parameters": [
         {
@@ -986,6 +1102,9 @@
                   "type": "number",
                   "description": "The id of the inbox",
                   "required": true
+                },
+                "source_id": {
+                  "$ref": "#/parameters/source_id"
                 }
               }
             }
@@ -1010,6 +1129,33 @@
         }
       }
     },
+    "/accounts/{account_id}/contacts/{id}/contactable_inboxes": {
+      "get": {
+        "tags": [
+          "Contact"
+        ],
+        "operationId": "contactableInboxesGet",
+        "description": "Get List of contactable Inboxes",
+        "summary": "Get Contactable Inboxes",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/contactable_inboxes"
+            }
+          },
+          "401": {
+            "description": "Authentication error",
+            "schema": {
+              "$ref": "#/definitions/bad_request_error"
+            }
+          },
+          "422": {
+            "description": "Incorrect payload"
+          }
+        }
+      }
+    },
     "/profile": {
       "get": {
         "tags": [
@@ -1471,6 +1617,18 @@
         }
       }
     },
+    "contactable_inboxes": {
+      "type": "object",
+      "properties": {
+        "source_id": {
+          "type": "string",
+          "description": "Contact Inbox Source Id"
+        },
+        "inbox": {
+          "$ref": "#/definitions/inbox"
+        }
+      }
+    },
     "account": {
       "type": "object",
       "properties": {
@@ -1904,6 +2062,10 @@
       "required": true,
       "description": "The id of the team to be updated"
     },
+    "source_id": {
+      "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",