docs: Add documentation for integration APIs (#2300)

app/views/api/v1/models/_app.json.jbuilder

@@ -3,4 +3,8 @@ json.name resource.name
 json.description resource.description
 json.enabled resource.enabled?(@current_account)
 json.button resource.action
-json.hooks @current_account.hooks.where(app_id: resource.id)
+json.hooks do
+  json.array! @current_account.hooks.where(app_id: resource.id) do |hook|
+    json.partial! 'api/v1/models/hook.json.jbuilder', resource: hook
+  end
+end

app/views/api/v1/models/_hook.json.jbuilder

@@ -1,4 +1,7 @@
 json.id resource.id
-json.app resource.app.params.to_h
+json.app_id resource.app_id
-json.enabled resource.enabled?
+json.status resource.enabled?
 json.inbox_id resource.inbox_id
+json.account_id resource.account_id
+json.hook_type resource.hook_type
+json.settings resource.settings

spec/controllers/api/v1/accounts/integrations/hooks_controller_spec.rb

@@ -36,7 +36,7 @@ RSpec.describe 'Integration Hooks API', type: :request do
 
         expect(response).to have_http_status(:success)
         data = JSON.parse(response.body)
-        expect(data['app']['id']).to eq params[:app_id]
+        expect(data['app_id']).to eq params[:app_id]
       end
     end
   end
@@ -72,7 +72,7 @@ RSpec.describe 'Integration Hooks API', type: :request do
 
         expect(response).to have_http_status(:success)
         data = JSON.parse(response.body)
-        expect(data['app']['id']).to eq 'slack'
+        expect(data['app_id']).to eq 'slack'
       end
     end
   end

swagger/definitions/index.yml

@@ -27,6 +27,10 @@ account:
   $ref: ./resource/account.yml
 team:
   $ref: ./resource/team.yml
+integrations_app:
+   $ref: ./resource/integrations/app.yml
+integrations_hook:
+   $ref: ./resource/integrations/hook.yml
 
 # RESPONSE
 
@@ -87,3 +91,9 @@ conversation_message_create:
 
 team_create_update_payload:
   $ref: ./request/team/create_update_payload.yml
+
+integrations_hook_create_payload:
+  $ref: ./request/integrations/hook_create_payload.yml
+
+integrations_hook_update_payload:
+  $ref: ./request/integrations/hook_update_payload.yml

swagger/definitions/request/integrations/hook_create_payload.yml

@@ -0,0 +1,11 @@
+type: object
+properties:
+  app_id:
+    type: string
+    description: The ID of app for which integration hook is being created
+  inbox_id:
+    type: string
+    description: The inbox ID, if the hook is an inbox hook
+  settings:
+    type: object
+    description: The settings required by the integration

swagger/definitions/request/integrations/hook_update_payload.yml

@@ -0,0 +1,5 @@
+type: object
+properties:
+  settings:
+    type: object
+    description: The settings required by the integration

swagger/definitions/resource/integrations/app.yml

@@ -0,0 +1,23 @@
+type: object
+properties:
+  id:
+    type: string
+    description: The ID of the integration
+  name:
+    type: string
+    description: The name of the integration
+  description:
+    type: string
+    description: The description about the team
+  hook_type:
+    type: string
+    description: Whether the integration is an account or inbox integration
+  enabled:
+    type: boolean
+    description: Whether the integration is enabled for the account
+  allow_multiple_hooks:
+    type: boolean
+    description: Whether multiple hooks can be created for the integration
+  hooks:
+    type: array
+    description: If there are any hooks created for this integration

swagger/definitions/resource/integrations/hook.yml

@@ -0,0 +1,23 @@
+type: object
+properties:
+  id:
+    type: string
+    description: The ID of the integration hook
+  app_id:
+    type: string
+    description: The ID of the integration app
+  inbox_id:
+    type: string
+    description: Inbox ID if its an Inbox integration
+  account_id:
+    type: string
+    description: Account ID of the integration
+  status:
+    type: boolean
+    description: Whether the integration hook is enabled for the account
+  hook_type:
+    type: boolean
+    description: Whether its an account or inbox integration hook
+  settings:
+    type: object
+    description: The associated settings for the integration

swagger/definitions/resource/team.yml

@@ -2,7 +2,7 @@ type: object
 properties:
   id:
     type: number
-    description: The id of the team
+    description: The ID of the team
   name:
     type: string
     description: The name of the team
@@ -14,7 +14,7 @@ properties:
     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
+    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/parameters/hook_id.yml

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

swagger/parameters/index.yml

@@ -4,6 +4,9 @@ account_id:
 team_id:
   $ref: ./team_id.yml
 
+hook_id:
+  $ref: ./hook_id.yml
+
 source_id:
   $ref: ./source_id.yml
 

swagger/parameters/team_id.yml

@@ -3,4 +3,4 @@ name: id
 schema:
   type: integer
 required: true
-description: The id of the team to be updated
+description: The ID of the team to be updated

swagger/paths/contact/conversations.yml

@@ -7,7 +7,7 @@ get:
     - name: id
       in: path
       type: number
-      description: id of the contact
+      description: ID of the contact
       required: true
   responses:
     200:

swagger/paths/contact/crud.yml

@@ -7,7 +7,7 @@ get:
     - name: id
       in: path
       type: number
-      description: id of the contact
+      description: ID of the contact
       required: true
   responses:
     200:
@@ -28,7 +28,7 @@ put:
     - name: id
       in: path
       type: number
-      description: id of the contact
+      description: ID of the contact
       required: true
     - name: data
       in: body

swagger/paths/contact_inboxes/create.yml

@@ -13,7 +13,7 @@ post:
         properties:
           inbox_id:
             type: number
-            description: The id of the inbox
+            description: The ID of the inbox
             required: true
           source_id:
             $ref: '#/parameters/source_id'

swagger/paths/conversation/update_last_seen.yml

@@ -8,7 +8,7 @@ post:
     - name: id
       in: path
       type: number
-      description: id of the conversation
+      description: ID of the conversation
       required: true
   responses:
     200:

swagger/paths/index.yml

@@ -113,3 +113,20 @@
     $ref: ./teams/update.yml
   delete:
     $ref: ./teams/delete.yml
+
+
+# Integrations
+/accounts/{account_id}/integrations/apps:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: './integrations/apps/show.yml'
+  
+ 
+/accounts/{account_id}/integrations/hooks:
+  post:
+    $ref: './integrations/hooks/create.yml'
+  patch:
+    $ref: ./integrations/hooks/update.yml
+  delete:
+    $ref: ./integrations/hooks/delete.yml

swagger/paths/integrations/apps/show.yml

@@ -0,0 +1,14 @@
+tags:
+  - Integrations
+operationId: get-details-of-all-integrations
+summary: List all the Integrations
+description: Get the details of all Integrations available for the account
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/integrations_app'
+  401:
+    description: Unauthorized
+  404:
+    description: Url not found

swagger/paths/integrations/hooks/create.yml

@@ -0,0 +1,19 @@
+tags:
+  - Integrations
+operationId: create-an-integration-hook
+summary: Create an integration hook
+description: Create an integration hook
+parameters:
+  - $ref: '#/parameters/account_id'
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/integrations_hook_create_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/integrations_hook'
+  401:
+    description: Unauthorized

swagger/paths/integrations/hooks/delete.yml

@@ -0,0 +1,15 @@
+tags:
+  -  Integrations
+operationId: delete-an-integration-hook
+summary: Delete an Integration Hook
+description: Delete an Integration Hook
+parameters:
+  - $ref: '#/parameters/account_id'
+  - $ref: '#/parameters/hook_id'
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The hook does not exist in the account

swagger/paths/integrations/hooks/update.yml

@@ -0,0 +1,20 @@
+tags:
+  - Integrations
+operationId: update-an-integrations-hook
+summary: Update an Integration Hook
+description: Update an Integration Hook
+parameters:
+  - $ref: '#/parameters/account_id'
+  - $ref: '#/parameters/hook_id'
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/integrations_hook_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/integrations_hook'
+  401:
+    description: Unauthorized

swagger/paths/teams/show.yml

@@ -11,4 +11,4 @@ responses:
   401:
     description: Unauthorized
   404:
-    description: The given team id does not exist in the account
+    description: The given team ID does not exist in the account

swagger/swagger.json

@@ -957,7 +957,7 @@
             "name": "id",
             "in": "path",
             "type": "number",
-            "description": "id of the contact",
+            "description": "ID of the contact",
             "required": true
           }
         ],
@@ -987,7 +987,7 @@
             "name": "id",
             "in": "path",
             "type": "number",
-            "description": "id of the contact",
+            "description": "ID of the contact",
             "required": true
           },
           {
@@ -1027,7 +1027,7 @@
             "name": "id",
             "in": "path",
             "type": "number",
-            "description": "id of the contact",
+            "description": "ID of the contact",
             "required": true
           }
         ],
@@ -1107,7 +1107,7 @@
               "properties": {
                 "inbox_id": {
                   "type": "number",
-                  "description": "The id of the inbox",
+                  "description": "The ID of the inbox",
                   "required": true
                 },
                 "source_id": {
@@ -1269,7 +1269,7 @@
             "description": "Unauthorized"
           },
           "404": {
-            "description": "The given team id does not exist in the account"
+            "description": "The given team ID does not exist in the account"
           }
         }
       },
@@ -1321,6 +1321,131 @@
           }
         }
       }
+    },
+    "/accounts/{account_id}/integrations/apps": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Integrations"
+        ],
+        "operationId": "get-details-of-all-integrations",
+        "summary": "List all the Integrations",
+        "description": "Get the details of all Integrations available for the account",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/integrations_app"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "Url not found"
+          }
+        }
+      }
+    },
+    "/accounts/{account_id}/integrations/hooks": {
+      "post": {
+        "tags": [
+          "Integrations"
+        ],
+        "operationId": "create-an-integration-hook",
+        "summary": "Create an integration hook",
+        "description": "Create an integration hook",
+        "parameters": [
+          {
+            "$ref": "#/parameters/account_id"
+          },
+          {
+            "name": "data",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/integrations_hook_create_payload"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/integrations_hook"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Integrations"
+        ],
+        "operationId": "update-an-integrations-hook",
+        "summary": "Update an Integration Hook",
+        "description": "Update an Integration Hook",
+        "parameters": [
+          {
+            "$ref": "#/parameters/account_id"
+          },
+          {
+            "$ref": "#/parameters/hook_id"
+          },
+          {
+            "name": "data",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/integrations_hook_update_payload"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/integrations_hook"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Integrations"
+        ],
+        "operationId": "delete-an-integration-hook",
+        "summary": "Delete an Integration Hook",
+        "description": "Delete an Integration Hook",
+        "parameters": [
+          {
+            "$ref": "#/parameters/account_id"
+          },
+          {
+            "$ref": "#/parameters/hook_id"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "The hook does not exist in the account"
+          }
+        }
+      }
     }
   },
   "definitions": {
@@ -1662,7 +1787,7 @@
       "properties": {
         "id": {
           "type": "number",
-          "description": "The id of the team"
+          "description": "The ID of the team"
         },
         "name": {
           "type": "string",
@@ -1678,7 +1803,7 @@
         },
         "account_id": {
           "type": "number",
-          "description": "The id of the account with the team is a part of"
+          "description": "The ID of the account with the team is a part of"
         },
         "is_member": {
           "type": "boolean",
@@ -1686,6 +1811,72 @@
         }
       }
     },
+    "integrations_app": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The ID of the integration"
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the integration"
+        },
+        "description": {
+          "type": "string",
+          "description": "The description about the team"
+        },
+        "hook_type": {
+          "type": "string",
+          "description": "Whether the integration is an account or inbox integration"
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether the integration is enabled for the account"
+        },
+        "allow_multiple_hooks": {
+          "type": "boolean",
+          "description": "Whether multiple hooks can be created for the integration"
+        },
+        "hooks": {
+          "type": "array",
+          "description": "If there are any hooks created for this integration"
+        }
+      }
+    },
+    "integrations_hook": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The ID of the integration hook"
+        },
+        "app_id": {
+          "type": "string",
+          "description": "The ID of the integration app"
+        },
+        "inbox_id": {
+          "type": "string",
+          "description": "Inbox ID if its an Inbox integration"
+        },
+        "account_id": {
+          "type": "string",
+          "description": "Account ID of the integration"
+        },
+        "status": {
+          "type": "boolean",
+          "description": "Whether the integration hook is enabled for the account"
+        },
+        "hook_type": {
+          "type": "boolean",
+          "description": "Whether its an account or inbox integration hook"
+        },
+        "settings": {
+          "type": "object",
+          "description": "The associated settings for the integration"
+        }
+      }
+    },
     "extended_contact": {
       "allOf": [
         {
@@ -2048,6 +2239,32 @@
           "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"
         }
       }
+    },
+    "integrations_hook_create_payload": {
+      "type": "object",
+      "properties": {
+        "app_id": {
+          "type": "string",
+          "description": "The ID of app for which integration hook is being created"
+        },
+        "inbox_id": {
+          "type": "string",
+          "description": "The inbox ID, if the hook is an inbox hook"
+        },
+        "settings": {
+          "type": "object",
+          "description": "The settings required by the integration"
+        }
+      }
+    },
+    "integrations_hook_update_payload": {
+      "type": "object",
+      "properties": {
+        "settings": {
+          "type": "object",
+          "description": "The settings required by the integration"
+        }
+      }
     }
   },
   "parameters": {
@@ -2067,7 +2284,16 @@
         "type": "integer"
       },
       "required": true,
-      "description": "The id of the team to be updated"
+      "description": "The ID of the team to be updated"
+    },
+    "hook_id": {
+      "in": "path",
+      "name": "hook_id",
+      "schema": {
+        "type": "integer"
+      },
+      "required": true,
+      "description": "The numeric ID of the integration hook"
     },
     "source_id": {
       "type": "string",