feat: Update swagger to openapi 3.0.4, update request payloads with examples (#11374)

app/controllers/api/v1/accounts/articles_controller.rb

@@ -68,7 +68,7 @@ class Api::V1::Accounts::ArticlesController < Api::V1::Accounts::BaseController
 
   def article_params
     params.require(:article).permit(
-      :title, :slug, :position, :content, :description, :position, :category_id, :author_id, :associated_article_id, :status,
+      :title, :slug, :position, :content, :description, :category_id, :author_id, :associated_article_id, :status,
       :locale, meta: [:title,
                       :description,
                       { tags: [] }]

swagger/definitions/error/bad_request.yml

@@ -6,4 +6,4 @@ properties:
   errors:
     type: array
     items:
-      $ref: '#/definitions/request_error'
+      $ref: '#/components/schemas/request_error'

swagger/definitions/index.yml

@@ -1,13 +1,11 @@
-##  ---------- ERRORS ------------- ##
+## ---------- ERRORS -------------- ##
 ## -------------------------------- ##
 bad_request_error:
   $ref: ./error/bad_request.yml
 request_error:
   $ref: ./error/request.yml
 
-
+## ---------- RESOURCE ------------ ##
-
-##  ---------- RESOURCE ------------- ##
 ## -------------------------------- ##
 
 generic_id:
@@ -24,10 +22,6 @@ category:
   $ref: ./resource/category.yml
 article:
   $ref: ./resource/article.yml
-category:
-  $ref: ./resource/category.yml
-article:
-  $ref: ./resource/article.yml
 contact:
   $ref: ./resource/contact.yml
 conversation:
@@ -52,6 +46,8 @@ webhook:
   $ref: ./resource/webhook.yml
 account:
   $ref: ./resource/account.yml
+account_user:
+  $ref: ./resource/account_user.yml
 platform_account:
   $ref: ./resource/platform_account.yml
 team:
@@ -71,13 +67,18 @@ public_message:
 public_inbox:
   $ref: ./resource/public/inbox.yml
 
-
+## ---------- REQUEST ------------- ##
-##  ---------- REQUEST------------- ##
 ## -------------------------------- ##
 
 account_create_update_payload:
   $ref: ./request/account/create_update_payload.yml
 
+account_user_create_update_payload:
+  $ref: ./request/account_user/create_update_payload.yml
+
+platform_agent_bot_create_update_payload:
+  $ref: ./request/platform/agent_bot/create_update_payload.yml
+
 agent_bot_create_update_payload:
   $ref: ./request/agent_bot/create_update_payload.yml
 
@@ -89,21 +90,36 @@ canned_response_create_update_payload:
 
 custom_attribute_create_update_payload:
   $ref: ./request/custom_attribute/create_update_payload.yml
-## contact
-contact_create:
-  $ref: ./request/contact/create.yml
-contact_update:
-  $ref: ./request/contact/update.yml
 
-## conversation
+## Agent
-conversation_message_create:
+agent_create_payload:
-  $ref: ./request/conversation/create_message.yml
+  $ref: ./request/agent/create_payload.yml
+agent_update_payload:
+  $ref: ./request/agent/update_payload.yml
 
-# Team request Payload
+## Contact
+contact_create_payload:
+  $ref: ./request/contact/create_payload.yml
+contact_update_payload:
+  $ref: ./request/contact/update_payload.yml
+
+## Conversation
+conversation_create_payload:
+  $ref: ./request/conversation/create_payload.yml
+conversation_message_create_payload:
+  $ref: ./request/conversation/create_message_payload.yml
+
+# Inbox
+inbox_create_payload:
+  $ref: ./request/inbox/create_payload.yml
+inbox_update_payload:
+  $ref: ./request/inbox/update_payload.yml
+
+# Team
 team_create_update_payload:
   $ref: ./request/team/create_update_payload.yml
 
-# Custom Filter request Payload
+# Custom Filter
 custom_filter_create_update_payload:
   $ref: ./request/custom_filter/create_update_payload.yml
 
@@ -128,7 +144,6 @@ category_create_update_payload:
 article_create_update_payload:
   $ref: ./request/portal/article_create_update_payload.yml
 
-
 ## public requests
 public_contact_create_update_payload:
   $ref: ./request/public/contact/create_update_payload.yml
@@ -141,37 +156,37 @@ public_message_update_payload:
 public_conversation_create_payload:
   $ref: ./request/public/conversation/create_payload.yml
 
-##  ---------- RESPONSE ------------- ##
+## ---------- RESPONSE ------------ ##
 ## -------------------------------- ##
 
-## contact
+## Contact
 extended_contact:
   allOf:
-    - $ref: '#/definitions/contact'
+    - $ref: '#/components/schemas/contact'
     - $ref: ./resource/extension/contact/show.yml
 contact_base:
   allOf:
-    - $ref: '#/definitions/generic_id'
+    - $ref: '#/components/schemas/generic_id'
-    - $ref: '#/definitions/contact'
+    - $ref: '#/components/schemas/contact'
 contact_list:
   type: array
   description: 'array of contacts'
   items:
     allOf:
-      - $ref: '#/definitions/generic_id'
+      - $ref: '#/components/schemas/generic_id'
-      - $ref: '#/definitions/contact'
+      - $ref: '#/components/schemas/contact'
 contact_conversations:
   type: array
   description: 'array of conversations'
   items:
     allOf:
-      - $ref: '#/definitions/conversation'
+      - $ref: '#/components/schemas/conversation'
       - $ref: ./resource/extension/contact/conversation.yml
       - $ref: ./resource/extension/conversation/with_display_id.yml
 contact_labels:
   $ref: ./resource/extension/contact/labels.yml
 
-## conversation
+## Conversation
 conversation_list:
   $ref: ./resource/extension/conversation/list.yml
 conversation_show:
@@ -181,8 +196,7 @@ conversation_status_toggle:
 conversation_labels:
   $ref: ./resource/extension/conversation/labels.yml
 
-
+## Report
-## report
 account_summary:
   $ref: './resource/reports/summary.yml'
 agent_conversation_metrics:

swagger/definitions/request/account/create_update_payload.yml

@@ -3,3 +3,29 @@ properties:
   name:
     type: string
     description: Name of the account
+    example: 'My Account'
+  locale:
+    type: string
+    description: The locale of the account
+    example: 'en'
+  domain:
+    type: string
+    description: The domain of the account
+    example: 'example.com'
+  support_email:
+    type: string
+    description: The support email of the account
+    example: 'support@example.com'
+  status:
+    type: string
+    enum: ['active', 'suspended']
+    description: The status of the account
+    example: 'active'
+  limits:
+    type: object
+    description: The limits of the account
+    example: {}
+  custom_attributes:
+    type: object
+    description: The custom attributes of the account
+    example: {}

swagger/definitions/request/account_user/create_update_payload.yml

@@ -0,0 +1,13 @@
+type: object
+required:
+  - user_id
+  - role
+properties:
+  user_id:
+    type: integer
+    description: The ID of the user
+    example: 1
+  role:
+    type: string
+    description: whether user is an administrator or agent
+    example: administrator

swagger/definitions/request/agent/create_payload.yml

@@ -0,0 +1,28 @@
+type: object
+required:
+  - name
+  - email
+  - role
+properties:
+  name:
+    type: string
+    description: Full Name of the agent
+    example: 'John Doe'
+  email:
+    type: string
+    description: Email of the Agent
+    example: 'john.doe@acme.inc'
+  role:
+    type: string
+    enum: ['agent', 'administrator']
+    description: Whether its administrator or agent
+    example: 'agent'
+  availability_status:
+    type: string
+    enum: ['available', 'busy', 'offline']
+    description: The availability setting of the agent.
+    example: 'available'
+  auto_offline:
+    type: boolean
+    description: Whether the availability status of agent is configured to go offline automatically when away.
+    example: true

swagger/definitions/request/agent/update_payload.yml

@@ -0,0 +1,18 @@
+type: object
+required:
+  - role
+properties:
+  role:
+    type: string
+    enum: ['agent', 'administrator']
+    description: Whether its administrator or agent
+    example: 'agent'
+  availability_status:
+    type: string
+    enum: ['available', 'busy', 'offline']
+    description: The availability status of the agent.
+    example: 'available'
+  auto_offline:
+    type: boolean
+    description: Whether the availability status of agent is configured to go offline automatically when away.
+    example: true

swagger/definitions/request/agent_bot/create_update_payload.yml

@@ -3,9 +3,28 @@ properties:
   name:
     type: string
     description: The name of the agent bot
+    example: 'My Agent Bot'
   description:
     type: string
-    description: The description about the agent bot
+    description: The description of the agent bot
+    example: 'This is a sample agent bot'
   outgoing_url:
     type: string
     description: The webhook URL for the bot
+    example: 'https://example.com/webhook'
+  avatar:
+    type: string
+    format: binary
+    description: Send the form data with the avatar image binary or use the avatar_url
+  avatar_url:
+    type: string
+    description: The url to a jpeg, png file for the agent bot avatar
+    example: https://example.com/avatar.png
+  bot_type:
+    type: integer
+    description: The type of the bot (0 for webhook)
+    example: 0
+  bot_config:
+    type: object
+    description: The configuration for the bot
+    example: {}

swagger/definitions/request/automation_rule/create_update_payload.yml

@@ -36,6 +36,6 @@ properties:
       example:
         attribute_key: content
         filter_operator: contains
-        query_operator: nil
+        query_operator: OR
         values:
           - help

swagger/definitions/request/canned_response/create_update_payload.yml

@@ -3,6 +3,8 @@ properties:
   content:
     type: string
     description: Message content for canned response
+    example: 'Hello, {{contact.name}}! Welcome to our service.'
   short_code:
     type: string
     description: Short Code for quick access of the canned response
+    example: 'welcome'

swagger/definitions/request/contact/create_payload.yml

@@ -0,0 +1,44 @@
+type: object
+required:
+  - inbox_id
+properties:
+  inbox_id:
+    type: number
+    description: ID of the inbox to which the contact belongs
+    example: 1
+  name:
+    type: string
+    description: name of the contact
+    example: Alice
+  email:
+    type: string
+    description: email of the contact
+    example: alice@acme.inc
+  blocked:
+    type: boolean
+    description: whether the contact is blocked or not
+    example: false
+  phone_number:
+    type: string
+    description: phone number of the contact
+    example: '+123456789'
+  avatar:
+    type: string
+    format: binary
+    description: Send the form data with the avatar image binary or use the avatar_url
+  avatar_url:
+    type: string
+    description: The url to a jpeg, png file for the contact avatar
+    example: https://example.com/avatar.png
+  identifier:
+    type: string
+    description: A unique identifier for the contact in external system
+    example: '1234567890'
+  additional_attributes:
+    type: object
+    description: An object where you can store additional attributes for contact. example {"type":"customer", "age":30}
+    example: { 'type': 'customer', 'age': 30 }
+  custom_attributes:
+    type: object
+    description: An object where you can store custom attributes for contact. example {"type":"customer", "age":30}, this should have a valid custom attribute definition.
+    example: {}

swagger/definitions/request/contact/update.yml

@@ -1,25 +0,0 @@
-type: object
-properties:
-  name:
-    type: string
-    description: name of the contact
-  email:
-    type: string
-    description: email of the contact
-  phone_number:
-    type: string
-    description: phone number of the contact
-  avatar:
-    type: string
-    format: binary
-    description: Send the form data with the avatar image binary or use the avatar_url
-  avatar_url:
-    type: string
-    description: The url to a jpeg, png file for the contact avatar
-  identifier:
-    type: string
-    description: A unique identifier for the contact in external system
-  custom_attributes:
-    type: object
-    description: An object where you can store custom attributes for contact. example {"type":"customer", "age":30}
-

swagger/definitions/request/contact/update_payload.yml

@@ -1,18 +1,21 @@
 type: object
-required:
-  - inbox_id
 properties:
-  inbox_id:
-    type: number
   name:
     type: string
     description: name of the contact
+    example: Alice
   email:
     type: string
     description: email of the contact
+    example: alice@acme.inc
+  blocked:
+    type: boolean
+    description: whether the contact is blocked or not
+    example: false
   phone_number:
     type: string
     description: phone number of the contact
+    example: '+123456789'
   avatar:
     type: string
     format: binary
@@ -20,9 +23,16 @@ properties:
   avatar_url:
     type: string
     description: The url to a jpeg, png file for the contact avatar
+    example: https://example.com/avatar.png
   identifier:
     type: string
     description: A unique identifier for the contact in external system
+    example: '1234567890'
+  additional_attributes:
+    type: object
+    description: An object where you can store additional attributes for contact. example {"type":"customer", "age":30}
+    example: { 'type': 'customer', 'age': 30 }
   custom_attributes:
     type: object
-    description: An object where you can store custom attributes for contact. example {"type":"customer", "age":30}
+    description: An object where you can store custom attributes for contact. example {"type":"customer", "age":30}, this should have a valid custom attribute definition.
+    example: {}

swagger/definitions/request/conversation/create_message_payload.yml

@@ -5,20 +5,29 @@ properties:
   content:
     type: string
     description: The content of the message
+    example: 'Hello, how can I help you?'
   message_type:
     type: string
     enum: ['outgoing', 'incoming']
+    description: The type of the message
+    example: 'outgoing'
   private:
     type: boolean
     description: Flag to identify if it is a private note
+    example: false
   content_type:
     type: string
-    enum: ['text', 'input_email', 'cards', 'input_select', 'form' , 'article']
+    enum: ['text', 'input_email', 'cards', 'input_select', 'form', 'article']
-    example: 'cards'
+    description: Content type of the message
-    description: 'if you want to create custom message types'
+    example: 'text'
   content_attributes:
     type: object
-    description: attributes based on your content type
+    description: Attributes based on the content type
+    example: {}
+  campaign_id:
+    type: integer
+    description: The campaign id to which the message belongs
+    example: 1
   template_params:
     type: object
     description: The template params for the message in case of whatsapp Channel
@@ -39,4 +48,4 @@ properties:
         type: object
         description: The processed param values for template variables in template
         example:
-          1: "Chatwoot"
+          1: 'Chatwoot'

swagger/definitions/request/conversation/create_payload.yml

@@ -0,0 +1,79 @@
+type: object
+required:
+  - source_id
+  - inbox_id
+properties:
+  source_id:
+    type: string
+    description: Conversation source id
+    example: '1234567890'
+  inbox_id:
+    type: integer
+    description: 'Id of inbox in which the conversation is created <br/> Allowed Inbox Types: Website, Phone, Api, Email'
+    example: 1
+  contact_id:
+    type: integer
+    description: Contact Id for which conversation is created
+    example: 1
+  additional_attributes:
+    type: object
+    description: Lets you specify attributes like browser information
+    example:
+      {
+        browser: 'Chrome',
+        browser_version: '89.0.4389.82',
+        os: 'Windows',
+        os_version: '10',
+      }
+  custom_attributes:
+    type: object
+    description: The object to save custom attributes for conversation, accepts custom attributes key and value
+    example: { attribute_key: attribute_value, priority_conversation_number: 3 }
+  status:
+    type: string
+    enum: ['open', 'resolved', 'pending']
+    description: Specify the conversation whether it's pending, open, closed
+    example: open
+  assignee_id:
+    type: integer
+    description: Agent Id for assigning a conversation to an agent
+    example: 1
+  team_id:
+    type: integer
+    description: Team Id for assigning a conversation to a team\
+    example: 1
+  snoozed_until:
+    type: string
+    format: date-time
+    description: Snoozed until date time
+    example: '2030-07-21T17:32:28Z'
+  message:
+    type: object
+    description: The initial message to be sent to the conversation
+    required: ['content']
+    properties:
+      content:
+        type: string
+        description: The content of the message
+        example: 'Hello, how can I help you?'
+      template_params:
+        type: object
+        description: The template params for the message in case of whatsapp Channel
+        properties:
+          name:
+            type: string
+            description: Name of the template
+            example: 'sample_issue_resolution'
+          category:
+            type: string
+            description: Category of the template
+            example: UTILITY
+          language:
+            type: string
+            description: Language of the template
+            example: en_US
+          processed_params:
+            type: object
+            description: The processed param values for template variables in template
+            example:
+              1: 'Chatwoot'

swagger/definitions/request/custom_attribute/create_update_payload.yml

@@ -3,20 +3,34 @@ properties:
   attribute_display_name:
     type: string
     description: Attribute display name
+    example: 'Custom Attribute'
   attribute_display_type:
     type: integer
     description: Attribute display type (text- 0, number- 1, currency- 2, percent- 3, link- 4, date- 5, list- 6, checkbox- 7)
+    example: 0
   attribute_description:
     type: string
     description: Attribute description
+    example: 'This is a custom attribute'
   attribute_key:
     type: string
     description: Attribute unique key value
+    example: 'custom_attribute'
   attribute_values:
     type: array
     description: Attribute values
     items:
       type: string
+    example: ['value1', 'value2']
   attribute_model:
     type: integer
     description: Attribute type(conversation_attribute- 0, contact_attribute- 1)
+    example: 0
+  regex_pattern:
+    type: string
+    description: Regex pattern (Only applicable for type- text). The regex pattern is used to validate the attribute value(s).
+    example: '^[a-zA-Z0-9]+$'
+  regex_cue:
+    type: string
+    description: Regex cue message (Only applicable for type- text). The cue message is shown when the regex pattern is not matched.
+    example: 'Please enter a valid value'

swagger/definitions/request/custom_filter/create_update_payload.yml

@@ -3,10 +3,13 @@ properties:
   name:
     type: string
     description: The name of the custom filter
+    example: 'My Custom Filter'
   type:
     type: string
-    enum: ["conversation", "contact", "report"]
+    enum: ['conversation', 'contact', 'report']
     description: The description about the custom filter
+    example: 'conversation'
   query:
     type: object
     description: A query that needs to be saved as a custom filter
+    example: {}

swagger/definitions/request/inbox/create_payload.yml

@@ -0,0 +1,88 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the inbox
+    example: 'Support'
+  avatar:
+    type: string
+    format: binary
+    description: Image file for avatar
+  greeting_enabled:
+    type: boolean
+    description: Enable greeting message
+    example: true
+  greeting_message:
+    type: string
+    description: Greeting message to be displayed on the widget
+    example: Hello, how can I help you?
+  enable_email_collect:
+    type: boolean
+    description: Enable email collection
+    example: true
+  csat_survey_enabled:
+    type: boolean
+    description: Enable CSAT survey
+    example: true
+  enable_auto_assignment:
+    type: boolean
+    description: Enable Auto Assignment
+    example: true
+  working_hours_enabled:
+    type: boolean
+    description: Enable working hours
+    example: true
+  out_of_office_message:
+    type: string
+    description: Out of office message to be displayed on the widget
+    example: We are currently out of office. Please leave a message and we will get back to you.
+  timezone:
+    type: string
+    description: Timezone of the inbox
+    example: 'America/New_York'
+  allow_messages_after_resolved:
+    type: boolean
+    description: Allow messages after conversation is resolved
+    example: true
+  lock_to_single_conversation:
+    type: boolean
+    description: Lock to single conversation
+    example: true
+  portal_id:
+    type: integer
+    description: Id of the help center portal to attach to the inbox
+    example: 1
+  sender_name_type:
+    type: string
+    description: Sender name type for the inbox
+    enum: ['friendly', 'professional']
+    example: 'friendly'
+  business_name:
+    type: string
+    description: Business name for the inbox
+    example: 'My Business'
+  channel:
+    type: object
+    properties:
+      type:
+        type: string
+        description: Type of the channel
+        enum:
+          ['web_widget', 'api', 'email', 'line', 'telegram', 'whatsapp', 'sms']
+        example: web_widget
+      website_url:
+        type: string
+        description: URL at which the widget will be loaded
+        example: 'https://example.com'
+      welcome_title:
+        type: string
+        description: Welcome title to be displayed on the widget
+        example: 'Welcome to our support'
+      welcome_tagline:
+        type: string
+        description: Welcome tagline to be displayed on the widget
+        example: 'We are here to help you'
+      widget_color:
+        type: string
+        description: A Hex-color string used to customize the widget
+        example: '#FF5733'

swagger/definitions/request/inbox/update_payload.yml

@@ -0,0 +1,82 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the inbox
+    example: 'Support'
+  avatar:
+    type: string
+    format: binary
+    description: Image file for avatar
+  greeting_enabled:
+    type: boolean
+    description: Enable greeting message
+    example: true
+  greeting_message:
+    type: string
+    description: Greeting message to be displayed on the widget
+    example: Hello, how can I help you?
+  enable_email_collect:
+    type: boolean
+    description: Enable email collection
+    example: true
+  csat_survey_enabled:
+    type: boolean
+    description: Enable CSAT survey
+    example: true
+  enable_auto_assignment:
+    type: boolean
+    description: Enable Auto Assignment
+    example: true
+  working_hours_enabled:
+    type: boolean
+    description: Enable working hours
+    example: true
+  out_of_office_message:
+    type: string
+    description: Out of office message to be displayed on the widget
+    example: We are currently out of office. Please leave a message and we will get back to you.
+  timezone:
+    type: string
+    description: Timezone of the inbox
+    example: 'America/New_York'
+  allow_messages_after_resolved:
+    type: boolean
+    description: Allow messages after conversation is resolved
+    example: true
+  lock_to_single_conversation:
+    type: boolean
+    description: Lock to single conversation
+    example: true
+  portal_id:
+    type: integer
+    description: Id of the help center portal to attach to the inbox
+    example: 1
+  sender_name_type:
+    type: string
+    description: Sender name type for the inbox
+    enum: ['friendly', 'professional']
+    example: 'friendly'
+  business_name:
+    type: string
+    description: Business name for the inbox
+    example: 'My Business'
+  channel:
+    type: object
+    properties:
+      website_url:
+        type: string
+        description: URL at which the widget will be loaded
+        example: 'https://example.com'
+      welcome_title:
+        type: string
+        description: Welcome title to be displayed on the widget
+        example: 'Welcome to our support'
+      welcome_tagline:
+        type: string
+        description: Welcome tagline to be displayed on the widget
+        example: 'We are here to help you'
+      widget_color:
+        type: string
+        description: A Hex-color string used to customize the widget
+        example: '#FF5733'

swagger/definitions/request/integrations/hook_create_payload.yml

@@ -1,11 +1,18 @@
 type: object
 properties:
   app_id:
-    type: string
+    type: integer
     description: The ID of app for which integration hook is being created
+    example: 1
   inbox_id:
-    type: string
+    type: integer
     description: The inbox ID, if the hook is an inbox hook
+    example: 1
+  status:
+    type: integer
+    description: The status of the integration (0 for inactive, 1 for active)
+    example: 1
   settings:
     type: object
     description: The settings required by the integration
+    example: {}

swagger/definitions/request/integrations/hook_update_payload.yml

@@ -1,5 +1,10 @@
 type: object
 properties:
+  status:
+    type: integer
+    description: The status of the integration (0 for inactive, 1 for active)
+    example: 1
   settings:
     type: object
     description: The settings required by the integration
+    example: {}

swagger/definitions/request/platform/agent_bot/create_update_payload.yml

@@ -0,0 +1,26 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the agent bot
+    example: 'My Agent Bot'
+  description:
+    type: string
+    description: The description of the agent bot
+    example: 'This is a sample agent bot'
+  outgoing_url:
+    type: string
+    description: The webhook URL for the bot
+    example: 'https://example.com/webhook'
+  account_id:
+    type: integer
+    description: The account ID to associate the agent bot with
+    example: 1
+  avatar:
+    type: string
+    format: binary
+    description: Send the form data with the avatar image binary or use the avatar_url
+  avatar_url:
+    type: string
+    description: The url to a jpeg, png file for the agent bot avatar
+    example: https://example.com/avatar.png

swagger/definitions/request/portal/article_create_update_payload.yml

@@ -1,34 +1,51 @@
 type: object
 properties:
-  content:
+  title:
     type: string
-    description: The text content.
+    description: The title of the article
-  meta:
+    example: 'Article Title'
-    type: object
+  slug:
-    description: Use for search
+    type: string
-    example: { tags: ['article_name'],  title: 'article title', description: 'article description' }
+    description: The slug of the article
+    example: 'article-title'
   position:
     type: integer
     description: article position in category
-  status:
+    example: 1
-    type: integer
+  content:
-    example: ['draft', 'published', 'archived']
-  title:
     type: string
-  slug:
+    description: The text content.
+    example: 'This is the content of the article'
+  description:
     type: string
-  views:
+    description: The description of the article
-    type: integer
+    example: 'This is the description of the article'
-  portal_id:
-    type: integer
-  account_id:
-    type: integer
-  author_id:
-    type: integer
   category_id:
     type: integer
-  folder_id:
+    description: The category id of the article
+    example: 1
+  author_id:
     type: integer
+    description: The author agent id of the article
+    example: 1
   associated_article_id:
     type: integer
     description: To associate similar articles to each other, e.g to provide the link for the reference.
+    example: 2
+  status:
+    type: integer
+    description: The status of the article. 0 for draft, 1 for published, 2 for archived
+    example: 1
+  locale:
+    type: string
+    description: The locale of the article
+    example: 'en'
+  meta:
+    type: object
+    description: Use for search
+    example:
+      {
+        tags: ['article_name'],
+        title: 'article title',
+        description: 'article description',
+      }

swagger/definitions/request/portal/category_create_update_payload.yml

@@ -1,28 +1,34 @@
 type: object
 properties:
-  description:
-    type: string
-    description: Category description
-  locale:
-    type: string
-    description: Category locale
-    example: en/es
   name:
     type: string
-    description: Category name
+    description: The name of the category
-  slug:
+    example: 'Category Name'
+  description:
     type: string
-    description: Category slug
+    description: A description for the category
+    example: 'Category description'
   position:
     type: integer
     description: Category position in the portal list to sort
-  portal_id:
+    example: 1
-    type: integer
+  slug:
-  account_id:
+    type: string
-    type: integer
+    description: The category slug used in the URL
-  associated_category_id:
+    example: 'category-name'
-    type: integer
+  locale:
-    description: To associate similar categories to each other, e.g same category of product documentation in different languages
+    type: string
+    description: The locale of the category
+    example: en
+  icon:
+    type: string
+    description: The icon of the category as a string (emoji)
+    example: '📚'
   parent_category_id:
     type: integer
     description: To define parent category, e.g product documentation has multiple level features in sales category or in engineering category.
+    example: 1
+  associated_category_id:
+    type: integer
+    description: To associate similar categories to each other, e.g same category of product documentation in different languages
+    example: 2

swagger/definitions/request/portal/portal_create_update_payload.yml

@@ -1,20 +1,13 @@
 type: object
 properties:
-  archived:
-    type: boolean
-    description: Status to check if portal is live
   color:
     type: string
-    description: Header color for help-center
+    description: Header color for help-center in hex format
-    example: add color HEX string, "#fffff"
+    example: '#FFFFFF'
-  config:
-    type: object
-    description: Configuration about supporting locales
-    example: { allowed_locales: ['en', 'es'], default_locale: 'en' }
   custom_domain:
     type: string
     description: Custom domain to display help center.
-    example: https://chatwoot.help/.
+    example: chatwoot.help
   header_text:
     type: string
     description: Help center header
@@ -26,11 +19,20 @@ properties:
   name:
     type: string
     description: Name for the portal
-  slug:
+    example: Handbook
-    type: string
-    description: Slug for the portal to display in link
   page_title:
     type: string
     description: Page title for the portal
-  account_id:
+    example: Handbook
-    type: integer
+  slug:
+    type: string
+    description: Slug for the portal to display in link
+    example: handbook
+  archived:
+    type: boolean
+    description: Status to check if portal is live
+    example: false
+  config:
+    type: object
+    description: Configuration about supporting locales
+    example: { allowed_locales: ['en', 'es'], default_locale: 'en' }

swagger/definitions/request/public/contact/create_update_payload.yml

@@ -1,24 +1,30 @@
-
 type: object
 properties:
   identifier:
     type: string
     description: External identifier of the contact
+    example: '1234567890'
   identifier_hash:
     type: string
     description: Identifier hash prepared for HMAC authentication
+    example: 'e93275d4eba0e5679ad55f5360af00444e2a888df9b0afa3e8b691c3173725f9'
   email:
     type: string
     description: Email of the contact
+    example: alice@acme.inc
   name:
     type: string
     description: Name of the contact
+    example: Alice
   phone_number:
     type: string
     description: Phone number of the contact
-  avatar_url:
+    example: '+123456789'
+  avatar:
     type: string
-    description: The url to a jpeg, png file for the user avatar
+    format: binary
+    description: Send the form data with the avatar image binary or use the avatar_url
   custom_attributes:
     type: object
     description: Custom attributes of the customer
+    example: {}

swagger/definitions/request/public/conversation/create_payload.yml

@@ -3,3 +3,4 @@ properties:
   custom_attributes:
     type: object
     description: Custom attributes of the conversation
+    example: {}

swagger/definitions/request/public/message/create_payload.yml

@@ -1,10 +1,10 @@
-
 type: object
 properties:
   content:
     type: string
     description: Content for the message
+    example: 'Hello, how can I help you?'
   echo_id:
     type: string
     description: Temporary identifier which will be passed back via websockets
-  
+    example: '1234567890'

swagger/definitions/request/public/message/update_payload.yml

@@ -1,6 +1,30 @@
-
 type: object
 properties:
   submitted_values:
     type: object
     description: Replies to the Bot Message Types
+    properties:
+      name:
+        type: string
+        description: The name of the submiitted value
+        example: 'My Name'
+      title:
+        type: string
+        description: The title of the submitted value
+        example: 'My Title'
+      value:
+        type: string
+        description: The value of the submitted value
+        example: 'value'
+      csat_survey_response:
+        type: object
+        description: The CSAT survey response
+        properties:
+          feedback_message:
+            type: string
+            description: The feedback message of the CSAT survey response
+            example: 'Great service!'
+          rating:
+            type: integer
+            description: The rating of the CSAT survey response
+            example: 5

swagger/definitions/request/team/create_update_payload.yml

@@ -3,9 +3,12 @@ properties:
   name:
     type: string
     description: The name of the team
+    example: Support Team
   description:
     type: string
     description: The description of the team
+    example: This is a team of support agents
   allow_auto_assign:
     type: boolean
     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
+    example: true

swagger/definitions/request/user/create_update_payload.yml

@@ -3,13 +3,20 @@ properties:
   name:
     type: string
     description: Name of the user
+    example: 'Daniel'
+  display_name:
+    type: string
+    description: Display name of the user
+    example: 'Dan'
   email:
     type: string
     description: Email of the user
+    example: 'daniel@acme.inc'
   password:
     type: string
     description: Password must contain uppercase, lowercase letters, number and a special character
+    example: 'Password2!'
   custom_attributes:
     type: object
     description: Custom attributes you want to associate with the user
-
+    example: {}

swagger/definitions/request/webhooks/create_update_payload.yml

@@ -3,16 +3,23 @@ properties:
   url:
     type: string
     description: The url where the events should be sent
+    example: https://example.com/webhook
   subscriptions:
     type: array
     items:
       type: string
-      enum: [
+      enum:
-        "conversation_created",
+        [
-        "conversation_status_changed",
+          'conversation_created',
-        "conversation_updated",
+          'conversation_status_changed',
-        "message_created",
+          'conversation_updated',
-        "message_updated",
+          'message_created',
-        "webwidget_triggered"
+          'message_updated',
+          'contact_created',
+          'contact_updated',
+          'webwidget_triggered',
         ]
     description: The events you want to subscribe to.
+    example:
+      - conversation_created
+      - conversation_status_changed

swagger/definitions/resource/account_user.yml

@@ -0,0 +1,14 @@
+type: array
+description: 'Array of account users'
+items:
+  type: object
+  properties:
+    account_id:
+      type: integer
+      description: The ID of the account
+    user_id:
+      type: integer
+      description: The ID of the user
+    role:
+      type: string
+      description: whether user is an administrator or agent

swagger/definitions/resource/agent.yml

@@ -29,4 +29,3 @@ properties:
   custom_attributes:
     type: object
     description: Available for users who are created through platform APIs and has custom attributes associated.
-

swagger/definitions/resource/contact.yml

@@ -24,8 +24,9 @@ properties:
           custom_attributes:
             type: object
             description: The object to save custom attributes for contact, accepts custom attributes key and value
-            example: { attribute_key: attribute_value, signed_up_at: dd/mm/yyyy }
+            example:
+              { attribute_key: attribute_value, signed_up_at: dd/mm/yyyy }
           contact_inboxes:
             type: array
             items:
-              $ref: '#/definitions/contact_inboxes'
+              $ref: '#/components/schemas/contact_inboxes'

swagger/definitions/resource/contact_inboxes.yml

@@ -5,4 +5,4 @@ properties:
     description: Contact Inbox Source Id
   inbox:
     type: object
-    $ref: '#/definitions/inbox'
+    $ref: '#/components/schemas/inbox'

swagger/definitions/resource/contactable_inboxes.yml

@@ -5,4 +5,4 @@ properties:
     description: Contact Inbox Source Id
   inbox:
     type: object
-    $ref: '#/definitions/inbox'
+    $ref: '#/components/schemas/inbox'

swagger/definitions/resource/conversation.yml

@@ -6,7 +6,7 @@ properties:
   messages:
     type: array
     items:
-      $ref: '#/definitions/message'
+      $ref: '#/components/schemas/message'
   account_id:
     type: number
     description: Account Id

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

@@ -19,4 +19,4 @@ properties:
             type: string
             description: Channel Type
       assignee:
-        $ref: '#/definitions/user'
+        $ref: '#/components/schemas/user'

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

@@ -19,6 +19,6 @@ properties:
         description: 'array of conversations'
         items:
           allOf:
-            - $ref: '#/definitions/generic_id'
+            - $ref: '#/components/schemas/generic_id'
-            - $ref: '#/definitions/conversation'
+            - $ref: '#/components/schemas/conversation'
             - $ref: '../contact/conversation.yml'

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

@@ -1,4 +1,4 @@
 type: object
 allOf:
-  - $ref: '#/definitions/conversation'
+  - $ref: '#/components/schemas/conversation'
   - $ref: '../contact/conversation.yml'

swagger/definitions/resource/portal.yml

@@ -27,8 +27,8 @@ properties:
   categories:
     type: array
     items:
-      $ref: '#/definitions/category'
+      $ref: '#/components/schemas/category'
   articles:
     type: array
     items:
-      $ref: '#/definitions/article'
+      $ref: '#/components/schemas/article'

swagger/definitions/resource/public/conversation.yml

@@ -9,7 +9,7 @@ properties:
   messages:
     type: array
     items:
-      $ref: '#/definitions/message'
+      $ref: '#/components/schemas/message'
     description: Messages in the conversation
   contact:
     type: object

swagger/definitions/resource/user.yml

@@ -25,4 +25,4 @@ properties:
   accounts:
     type: array
     items:
-      $ref: '#/definitions/account'
+      $ref: '#/components/schemas/account'

swagger/index.yml

@@ -1,23 +1,24 @@
-swagger: "2.0"
+openapi: '3.0.4'
 info:
-  description: This is the API documentation for Chatwoot server.
-  version: 1.0.0
   title: Chatwoot
+  description: This is the API documentation for Chatwoot server.
+  version: 1.1.0
   termsOfService: https://www.chatwoot.com/terms-of-service/
   contact:
     email: hello@chatwoot.com
   license:
     name: MIT License
     url: https://opensource.org/licenses/MIT
-host: app.chatwoot.com
+servers:
-basePath: /
+  - url: https://app.chatwoot.com/
-schemes:
+paths:
-  - https
+  $ref: ./paths/index.yml
-produces:
+components:
-- application/json; charset=utf-8
+  schemas:
-consumes:
+    $ref: ./definitions/index.yml
-- application/json; charset=utf-8
+  parameters:
-securityDefinitions:
+    $ref: ./parameters/index.yml
+  securitySchemes:
     userApiKey:
       type: apiKey
       in: header
@@ -33,15 +34,6 @@ securityDefinitions:
       in: header
       name: api_access_token
       description: This token can be obtained by the system admin after creating a platformApp. This token should be used to provision agent bots, accounts, users and their roles.
-security:
-  - userApiKey: []
-
-paths:
-  $ref: ./paths/index.yml
-definitions:
-  $ref: ./definitions/index.yml
-parameters:
-  $ref: ./parameters/index.yml
 
 x-tagGroups:
   - name: Platform
@@ -56,9 +48,6 @@ x-tagGroups:
       - Agents
       - Canned Responses
       - Contacts
-      - Contact Labels
-      - Conversation Assignment
-      - Conversation Labels
       - Conversations
       - Custom Attributes
       - Custom Filters

swagger/parameters/account_id.yml

@@ -1,5 +1,6 @@
 in: path
 name: account_id
-type: integer
+schema:
+  type: integer
 required: true
 description: The numeric ID of the account

swagger/parameters/agent_bot_id.yml

@@ -1,5 +1,6 @@
 in: path
 name: id
-type: integer
+schema:
+  type: integer
 required: true
 description: The ID of the agentbot to be updated

swagger/parameters/contact_sort.yml

@@ -1,7 +1,8 @@
 in: query
 name: sort
-type: string
+schema:
-enum:
+  type: string
+  enum:
     - name
     - email
     - phone_number

swagger/parameters/conversation_id.yml

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

swagger/parameters/conversation_uuid.yml

@@ -1,5 +1,6 @@
 in: path
 name: conversation_uuid
-type: integer
+schema:
+  type: integer
 required: true
 description: The uuid of the conversation

swagger/parameters/custom_filter_id.yml

@@ -1,5 +1,6 @@
 in: path
 name: custom_filter_id
-type: integer
+schema:
+  type: integer
 required: true
 description: The numeric ID of the custom filter

swagger/parameters/hook_id.yml

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

swagger/parameters/inbox_id.yml

@@ -1,5 +1,6 @@
 in: path
 name: inbox_id
-type: integer
+schema:
+  type: integer
 required: true
 description: The ID of the Inbox

swagger/parameters/message_id.yml

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

swagger/parameters/page.yml

@@ -1,6 +1,7 @@
 in: query
 name: page
-type: integer
+schema:
-default: 1
+  type: integer
+  default: 1
 required: false
 description: The page parameter

swagger/parameters/platform_user_id.yml

@@ -1,5 +1,6 @@
 in: path
 name: id
-type: integer
+schema:
+  type: integer
 required: true
 description: The numeric ID of the user on the platform

swagger/parameters/portal_id.yml

@@ -1,5 +1,6 @@
 in: path
-name: portal_id
+name: id
-type: integer
+schema:
+  type: string
 required: true
-description: The numeric ID of the portal
+description: The slug identifier of the portal

swagger/parameters/public/contact_identifier.yml

@@ -1,5 +1,6 @@
 in: path
 name: contact_identifier
-type: string
+schema:
+  type: string
 required: true
 description: The source id of contact obtained on contact create

swagger/parameters/public/inbox_identifier.yml

@@ -1,5 +1,6 @@
 in: path
 name: inbox_identifier
-type: string
+schema:
+  type: string
 required: true
 description: The identifier obtained from API inbox channel

swagger/parameters/report_metric.yml

@@ -1,7 +1,8 @@
 in: query
 name: metric
-type: string
+schema:
-enum:
+  type: string
+  enum:
     - conversations_count
     - incoming_messages_count
     - outgoing_messages_count

swagger/parameters/report_type.yml

@@ -1,7 +1,8 @@
 in: query
 name: type
-type: string
+schema:
-enum:
+  type: string
+  enum:
     - account
     - agent
     - inbox

swagger/parameters/source_id.yml

@@ -1,5 +1,6 @@
 in: path
 name: source_id
 required: true
-type: string
+schema:
+  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/parameters/team_id.yml

@@ -1,5 +1,6 @@
 in: path
 name: team_id
-type: integer
+schema:
+  type: integer
 required: true
 description: The ID of the team to be updated

swagger/parameters/webhook_id.yml

@@ -1,5 +1,6 @@
 in: path
 name: webhook_id
-type: integer
+schema:
+  type: integer
 required: true
 description: The numeric ID of the webhook

swagger/paths/application/agent_bots/create.yml

@@ -3,17 +3,24 @@ tags:
 operationId: create-an-account-agent-bot
 summary: Create an Agent Bot
 description: Create an agent bot in the account
-parameters:
+security:
-  - $ref: '#/parameters/account_id'
+  - userApiKey: []
-  - name: data
+requestBody:
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      $ref: '#/definitions/agent_bot_create_update_payload'
+        $ref: '#/components/schemas/agent_bot_create_update_payload'
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/agent_bot'
+          $ref: '#/components/schemas/agent_bot'
-  401:
+  '401':
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/agent_bots/delete.yml

@@ -3,10 +3,20 @@ tags:
 operationId: delete-an-account-agent-bot
 summary: Delete an AgentBot
 description: Delete an AgentBot from the account
+security:
+  - userApiKey: []
 responses:
   200:
     description: Success
   401:
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
   404:
     description: The agent bot does not exist in the account
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/agent_bots/index.yml

@@ -3,14 +3,21 @@ tags:
 operationId: list-all-account-agent-bots
 summary: List all AgentBots
 description: List all agent bots available for the current account
+security:
+  - userApiKey: []
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
           type: array
           description: 'Array of agent bots'
           items:
-        $ref: '#/definitions/agent_bot'
+            $ref: '#/components/schemas/agent_bot'
-
+  '401':
-  401:
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/agent_bots/show.yml

@@ -3,12 +3,24 @@ tags:
 operationId: get-details-of-a-single-account-agent-bot
 summary: Get an agent bot details
 description: Get the details of an agent bot in the account
+security:
+  - userApiKey: []
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/agent_bot'
+          $ref: '#/components/schemas/agent_bot'
-  401:
+  '401':
     description: Unauthorized
-  404:
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '404':
     description: The given agent bot ID does not exist in the account
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/agent_bots/update.yml

@@ -3,16 +3,24 @@ tags:
 operationId: update-an-account-agent-bot
 summary: Update an agent bot
 description: Update an agent bot's attributes
-parameters:
+security:
-  - name: data
+  - userApiKey: []
-    in: body
+requestBody:
   required: true
+  content:
+    application/json:
       schema:
-      $ref: '#/definitions/agent_bot_create_update_payload'
+        $ref: '#/components/schemas/agent_bot_create_update_payload'
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/agent_bot'
+          $ref: '#/components/schemas/agent_bot'
-  401:
+  '401':
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/agents/create.yml

@@ -5,39 +5,23 @@ summary: Add a New Agent
 description: Add a new Agent to Account
 security:
   - userApiKey: []
-parameters:
+requestBody:
-  - name: data
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      type: object
+        $ref: '#/components/schemas/agent_create_payload'
-      required:
-        - name
-        - email
-        - role
-      properties:
-        name:
-          type: string
-          description: Full Name of the agent
-        email:
-          type: string
-          description: Email of the Agent
-        role:
-          type: string
-          enum: ['agent', 'administrator']
-          description: Whether its administrator or agent
-        availability_status:
-          type: string
-          enum: ['available', 'busy', 'offline']
-          description: The availability setting of the agent.
-        auto_offline:
-          type: boolean
-          description: Whether the availability status of agent is configured to go offline automatically when away.
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
           description: 'Newly Created Agent'
-        $ref: '#/definitions/agent'
+          $ref: '#/components/schemas/agent'
-  403:
+  '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/agents/delete.yml

@@ -8,13 +8,22 @@ security:
 parameters:
   - in: path
     name: id
+    schema:
       type: integer
     required: true
-    description: The ID of the agent to be deleted
+    description: The ID of the agent to be deleted.
 responses:
   200:
     description: Success
   404:
     description: Agent not found
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
   403:
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/agents/index.yml

@@ -8,10 +8,16 @@ security:
 responses:
   200:
     description: Success
+    content:
+      application/json:
         schema:
           type: array
           description: 'Array of all active agents'
           items:
-          $ref: '#/definitions/agent'
+            $ref: '#/components/schemas/agent'
   403:
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/agents/update.yml

@@ -8,35 +8,33 @@ security:
 parameters:
   - in: path
     name: id
+    schema:
       type: integer
     required: true
     description: The ID of the agent to be updated.
-  - name: data
+requestBody:
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      type: object
+        $ref: '#/components/schemas/agent_update_payload'
-      required:
-        - role
-      properties:
-        role:
-          type: string
-          enum: ['agent', 'administrator']
-          description: Whether its administrator or agent
-        availability:
-          type: string
-          enum: ['available', 'busy', 'offline']
-          description: The availability setting of the agent.
-        auto_offline:
-          type: boolean
-          description: Whether the availability status of agent is configured to go offline automatically when away.
 responses:
   200:
     description: Success
+    content:
+      application/json:
         schema:
           description: 'The updated agent'
-        $ref: '#/definitions/agent'
+          $ref: '#/components/schemas/agent'
   404:
     description: Agent not found
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
   403:
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/article/create.yml

@@ -5,16 +5,22 @@ summary: Add a new article
 description: Add a new article to portal
 security:
   - userApiKey: []
-parameters:
+requestBody:
-  - name: data
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      $ref: '#/definitions/article_create_update_payload'
+        $ref: '#/components/schemas/article_create_update_payload'
 responses:
   '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/article'
+          $ref: '#/components/schemas/article'
   '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/automation_rule/create.yml

@@ -5,16 +5,22 @@ summary: Add a new automation rule
 description: Add a new automation rule to account
 security:
   - userApiKey: []
-parameters:
+requestBody:
-  - name: data
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      $ref: '#/definitions/automation_rule_create_update_payload'
+        $ref: '#/components/schemas/automation_rule_create_update_payload'
 responses:
   '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/automation_rule'
+          $ref: '#/components/schemas/automation_rule'
   '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/automation_rule/delete.yml

@@ -8,6 +8,7 @@ security:
 parameters:
   - in: path
     name: id
+    schema:
       type: integer
     required: true
     description: The ID of the automation rule to be deleted
@@ -16,5 +17,13 @@ responses:
     description: Success
   '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
   '404':
     description: automation rule not found
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/automation_rule/index.yml

@@ -3,18 +3,24 @@ tags:
 operationId: get-account-automation-rule
 summary: List all automation rules in an account
 parameters:
-  - $ref: '#/parameters/account_id'
+  - $ref: '#/components/parameters/account_id'
-  - $ref: '#/parameters/page'
+  - $ref: '#/components/parameters/page'
 description: Get details of automation rules in an Account
 security:
   - userApiKey: []
 responses:
   '200':
     description: Success
+    content:
+      application/json:
         schema:
           type: array
           description: Array of all automation rules
           items:
-        $ref: '#/definitions/automation_rule'
+            $ref: '#/components/schemas/automation_rule'
   '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/automation_rule/show.yml

@@ -3,18 +3,31 @@ tags:
 operationId: get-details-of-a-single-automation-rule
 summary: Get a automation rule details
 description: Get the details of a automation rule in the account
+security:
+  - userApiKey: []
 parameters:
   - in: path
     name: id
+    schema:
       type: integer
     required: true
     description: The ID of the automation rule to be updated.
 responses:
   '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/automation_rule'
+          $ref: '#/components/schemas/automation_rule'
   '401':
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
   '404':
     description: The given rule ID does not exist in the account
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/automation_rule/update.yml

@@ -8,20 +8,32 @@ security:
 parameters:
   - in: path
     name: id
+    schema:
       type: integer
     required: true
     description: The ID of the automation rule to be updated.
-  - name: data
+requestBody:
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      $ref: '#/definitions/automation_rule_create_update_payload'
+        $ref: '#/components/schemas/automation_rule_create_update_payload'
 responses:
   '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/automation_rule'
+          $ref: '#/components/schemas/automation_rule'
   '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
   '404':
     description: Rule not found
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/canned_responses/create.yml

@@ -5,17 +5,23 @@ summary: Add a New Canned Response
 description: Add a new Canned Response to Account
 security:
   - userApiKey: []
-parameters:
+requestBody:
-  - name: data
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      $ref: '#/definitions/canned_response_create_update_payload'
+        $ref: '#/components/schemas/canned_response_create_update_payload'
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
           description: 'Newly Created Canned Response'
-        $ref: '#/definitions/canned_response'
+          $ref: '#/components/schemas/canned_response'
-  403:
+  '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/canned_responses/delete.yml

@@ -8,13 +8,22 @@ security:
 parameters:
   - in: path
     name: id
+    schema:
       type: integer
     required: true
     description: The ID of the canned response to be deleted
 responses:
-  200:
+  '200':
     description: Success
-  404:
+  '404':
     description: Canned Response not found
-  403:
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/canned_responses/index.yml

@@ -6,12 +6,18 @@ description: Get Details of Canned Responses in an Account
 security:
   - userApiKey: []
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
           type: array
           description: 'Array of all canned responses'
           items:
-          $ref: '#/definitions/canned_response'
+            $ref: '#/components/schemas/canned_response'
-  403:
+  '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/canned_responses/update.yml

@@ -1,5 +1,5 @@
 tags:
-  - Canned Response
+  - Canned Responses
 operationId: update-canned-response-in-account
 summary: Update Canned Response in Account
 description: Update a Canned Response in Account
@@ -8,21 +8,33 @@ security:
 parameters:
   - in: path
     name: id
+    schema:
       type: integer
     required: true
     description: The ID of the canned response to be updated.
-  - name: data
+requestBody:
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      $ref: '#/definitions/canned_response_create_update_payload'
+        $ref: '#/components/schemas/canned_response_create_update_payload'
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
           description: 'The updated canned response'
-        $ref: '#/definitions/canned_response'
+          $ref: '#/components/schemas/canned_response'
-  404:
+  '404':
     description: Agent not found
-  403:
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/category/create.yml

@@ -5,16 +5,22 @@ summary: Add a new category
 description: Add a new category to portal
 security:
   - userApiKey: []
-parameters:
+requestBody:
-  - name: data
-    in: body
   required: true
+  content:
+    application/json:
       schema:
-      $ref: '#/definitions/category_create_update_payload'
+        $ref: '#/components/schemas/category_create_update_payload'
 responses:
   '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/category'
+          $ref: '#/components/schemas/category'
   '403':
     description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/contact_inboxes/create.yml

@@ -5,15 +5,19 @@ post:
   description: Create a contact inbox record for an inbox
   summary: Create contact inbox
   parameters:
-    - $ref: '#/parameters/account_id'
+    - $ref: '#/components/parameters/account_id'
     - name: id
       in: path
+      schema:
         type: number
       description: ID of the contact
       required: true
-    - name: data
+  security:
-      in: body
+    - userApiKey: []
+  requestBody:
     required: true
+    content:
+      application/json:
         schema:
           type: object
           required:
@@ -22,17 +26,26 @@ post:
             inbox_id:
               type: number
               description: The ID of the inbox
+              example: 1
             source_id:
               type: string
               description: Contact Inbox Source Id
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/contact_inboxes'
+            $ref: '#/components/schemas/contact_inboxes'
-    401:
+    '401':
       description: Authentication error
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/bad_request_error'
+            $ref: '#/components/schemas/bad_request_error'
-    422:
+    '422':
       description: Incorrect payload
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/contactable_inboxes/get.yml

@@ -4,21 +4,32 @@ get:
   operationId: contactableInboxesGet
   description: Get List of contactable Inboxes
   summary: Get Contactable Inboxes
+  security:
+    - userApiKey: []
   parameters:
-    - $ref: '#/parameters/account_id'
+    - $ref: '#/components/parameters/account_id'
     - name: id
       in: path
+      schema:
         type: number
       description: ID of the contact
       required: true
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/contactable_inboxes'
+            $ref: '#/components/schemas/contactable_inboxes'
-    401:
+    '401':
       description: Authentication error
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/bad_request_error'
+            $ref: '#/components/schemas/bad_request_error'
-    422:
+    '422':
       description: Incorrect payload
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/contacts/conversations.yml

@@ -1,22 +1,43 @@
+parameters:
+  - $ref: '#/components/parameters/account_id'
+  - name: id
+    in: path
+    required: true
+    schema:
+      type: number
+    description: ID of the contact
+
 get:
   tags:
     - Contacts
   operationId: contactConversations
   summary: Contact Conversations
-  description: Get conversations associated to that contact
+  description: Get conversations associated with that contact
   parameters:
-    - $ref: '#/parameters/account_id'
     - name: id
       in: path
+      required: true
+      schema:
         type: number
       description: ID of the contact
-      required: true
+  security:
+    - userApiKey: []
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/contact_conversations'
+            $ref: '#/components/schemas/contact_conversations'
-    404:
+    '404':
       description: Contact not found
-    403:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '403':
       description: Access denied
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/contacts/crud.yml

@@ -1,58 +1,94 @@
 parameters:
-  - $ref: '#/parameters/account_id'
+  - $ref: '#/components/parameters/account_id'
   - name: id
     in: path
+    required: true
+    schema:
       type: number
     description: ID of the contact
-    required: true
 
 get:
   tags:
     - Contacts
   operationId: contactDetails
   summary: Show Contact
+  security:
+    - userApiKey: []
   description: Get a contact belonging to the account using ID
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/extended_contact'
+            $ref: '#/components/schemas/extended_contact'
-    404:
+    '404':
       description: Contact not found
-    403:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '403':
       description: Access denied
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
 
 put:
   tags:
     - Contacts
   operationId: contactUpdate
   summary: Update Contact
+  security:
+    - userApiKey: []
   description: Update a contact belonging to the account using ID
-  parameters:
+  requestBody:
-    - name: data
-      in: body
     required: true
+    content:
+      application/json:
         schema:
-        $ref: '#/definitions/contact_update'
+          $ref: '#/components/schemas/contact_update_payload'
   responses:
-    204:
+    '204':
       description: Success
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/contact_base'
+            $ref: '#/components/schemas/contact_base'
-    404:
+    '404':
       description: Contact not found
-    403:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '403':
       description: Access denied
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
 
 delete:
   tags:
     - Contacts
   operationId: contactDelete
   summary: Delete Contact
+  security:
+    - userApiKey: []
+  description: Delete a contact belonging to the account using ID
   responses:
-    200:
+    '200':
       description: Success
-    401:
+    '401':
       description: Unauthorized
-    404:
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '404':
       description: Contact not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/contacts/filter.yml

@@ -1,18 +1,21 @@
-tags:
+post:
+  tags:
     - Contacts
-operationId: contactFilter
+  operationId: contactFilter
-description: Filter contacts with custom filter options and pagination
+  description: Filter contacts with custom filter options and pagination
-summary: Contact Filter
+  summary: Contact Filter
-security:
+  security:
     - userApiKey: []
-  - agentBotApiKey: []
+  parameters:
-parameters:
+    - $ref: '#/components/parameters/account_id'
     - name: page
       in: query
-    type: integer
+      schema:
-  - name: body
+        type: number
-    in: body
+  requestBody:
     required: true
+    content:
+      application/json:
         schema:
           type: object
           properties:
@@ -27,7 +30,7 @@ parameters:
                   filter_operator:
                     type: string
                     description: filter operator name
-                enum: [ equal_to, not_equal_to, contains, does_not_contain ]
+                    enum: [equal_to, not_equal_to, contains, does_not_contain]
                   values:
                     type: array
                     items:
@@ -36,7 +39,7 @@ parameters:
                   query_operator:
                     type: string
                     description: query operator name
-                enum: [ AND, OR ]
+                    enum: [AND, OR]
               example:
                 - attribute_key: 'name'
                   filter_operator: 'equal_to'
@@ -46,13 +49,16 @@ parameters:
                   filter_operator: 'equal_to'
                   values: ['us']
                   query_operator: null
-
+  responses:
-responses:
+    '200':
-  200:
       description: Success
+      content:
+        application/json:
           schema:
-      $ref: '#/definitions/contact_list'
+            $ref: '#/components/schemas/contact_list'
-  400:
+    '400':
       description: Bad Request Error
+      content:
+        application/json:
           schema:
-      $ref: '#/definitions/bad_request_error'
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/contacts/labels.yml

@@ -0,0 +1,79 @@
+parameters:
+  - $ref: '#/components/parameters/account_id'
+  - name: id
+    in: path
+    required: true
+    schema:
+      type: number
+    description: ID of the contact
+
+get:
+  tags:
+    - Contacts
+  operationId: list-all-labels-of-a-contact
+  summary: List Labels
+  description: Lists all the labels of a contact
+  security:
+    - userApiKey: []
+  responses:
+    '200':
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_labels'
+    '401':
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '404':
+      description: Contact not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+
+post:
+  tags:
+    - Contacts
+  operationId: contact-add-labels
+  summary: Add Labels
+  description: Add labels to a contact. Note that this API would overwrite the existing list of labels associated to the conversation.
+  security:
+    - userApiKey: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          required:
+            - labels
+          properties:
+            labels:
+              type: array
+              description: Array of labels (comma-separated strings)
+              items:
+                type: string
+              example: ['support', 'billing']
+  responses:
+    '200':
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_labels'
+    '401':
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '404':
+      description: Contact not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/contacts/labels/create.yml

@@ -1,26 +0,0 @@
-tags:
-  - Contact Labels
-operationId: contact-add-labels
-summary: Add Labels
-description: Add labels to a contact. 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)
-          items:
-            type: string
-responses:
-  200:
-    description: Success
-    schema:
-      $ref: '#/definitions/contact_labels'
-  404:
-    description: Contact not found
-  401:
-    description: Unauthorized

swagger/paths/application/contacts/labels/index.yml

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

swagger/paths/application/contacts/list_create.yml

@@ -2,21 +2,27 @@ get:
   tags:
     - Contacts
   operationId: contactList
-  description: Listing all the resolved contacts with pagination (Page size = 15) . Resolved contacts are the ones with a value for identifier, email or phone number
+  description: Listing all the resolved contacts with pagination (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number
   summary: List Contacts
+  security:
+    - userApiKey: []
   parameters:
-    - $ref: '#/parameters/account_id'
+    - $ref: '#/components/parameters/account_id'
-    - $ref: '#/parameters/contact_sort_param'
+    - $ref: '#/components/parameters/contact_sort_param'
-    - $ref: '#/parameters/page'
+    - $ref: '#/components/parameters/page'
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/contact_list'
+            $ref: '#/components/schemas/contact_list'
-    400:
+    '400':
       description: Bad Request Error
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/bad_request_error'
+            $ref: '#/components/schemas/bad_request_error'
 
 post:
   tags:
@@ -24,19 +30,26 @@ post:
   operationId: contactCreate
   description: Create a new Contact
   summary: Create Contact
+  security:
+    - userApiKey: []
   parameters:
-    - $ref: '#/parameters/account_id'
+    - $ref: '#/components/parameters/account_id'
-    - name: data
+  requestBody:
-      in: body
     required: true
+    content:
+      application/json:
         schema:
-        $ref: '#/definitions/contact_create'
+          $ref: '#/components/schemas/contact_create_payload'
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/extended_contact'
+            $ref: '#/components/schemas/extended_contact'
-    400:
+    '400':
       description: Bad Request Error
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/bad_request_error'
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/contacts/search.yml

@@ -4,23 +4,30 @@ get:
   operationId: contactSearch
   description: Search the resolved contacts using a search key, currently supports email search (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number
   summary: Search Contacts
+  security:
+    - userApiKey: []
   parameters:
-    - $ref: '#/parameters/account_id'
+    - $ref: '#/components/parameters/account_id'
     - name: q
       in: query
+      schema:
         type: string
       description: Search using contact `name`, `identifier`, `email` or `phone number`
-    - $ref: '#/parameters/contact_sort_param'
+    - $ref: '#/components/parameters/contact_sort_param'
-    - $ref: '#/parameters/page'
+    - $ref: '#/components/parameters/page'
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
             type: object
             properties:
               payload:
-            $ref: '#/definitions/contact_list'
+                $ref: '#/components/schemas/contact_list'
-    401:
+    '401':
       description: Authentication error
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/bad_request_error'
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/conversation/assignments.yml

@@ -1,30 +1,42 @@
 tags:
-  - Conversation Assignment
+  - Conversations
 operationId: assign-a-conversation
 summary: Assign Conversation
 description: Assign a conversation to an agent or a team
 security:
   - userApiKey: []
   - agentBotApiKey: []
-parameters:
+requestBody:
-  - name: data
-    in: body
   required: true
+  content:
+    application/json:
       schema:
         type: object
         properties:
           assignee_id:
             type: number
             description: Id of the assignee user
+            example: 1
           team_id:
             type: number
             description: Id of the team. If the assignee_id is present, this param would be ignored
+            example: 1
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/user'
+          $ref: '#/components/schemas/user'
-  404:
+  '401':
-    description: Conversation not found
-  401:
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '404':
+    description: Conversation not found
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/conversation/custom_attributes.yml

@@ -5,11 +5,10 @@ summary: Update Custom Attributes
 description: Updates the custom attributes of a conversation
 security:
   - userApiKey: []
-  - agentBotApiKey: []
+requestBody:
-parameters:
-  - name: data
-    in: body
   required: true
+  content:
+    application/json:
       schema:
         type: object
         required:
@@ -19,18 +18,28 @@ parameters:
             type: object
             description: The custom attributes to be set for the conversation
             example:
-            order_id: "12345"
+              order_id: '12345'
-            previous_conversation: "67890"
+              previous_conversation: '67890'
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
           type: object
           properties:
             custom_attributes:
               type: object
               description: The custom attributes of the conversation
-  404:
+  '401':
-    description: Conversation not found
-  401:
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '404':
+    description: Conversation not found
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/conversation/filter.yml

@@ -5,14 +5,15 @@ description: Filter conversations with custom filter options and pagination
 summary: Conversations Filter
 security:
   - userApiKey: []
-  - agentBotApiKey: []
 parameters:
   - name: page
     in: query
-    type: integer
+    schema:
-  - name: body
+      type: number
-    in: body
+requestBody:
   required: true
+  content:
+    application/json:
       schema:
         type: object
         properties:
@@ -27,7 +28,7 @@ parameters:
                 filter_operator:
                   type: string
                   description: filter operator name
-                enum: [ equal_to, not_equal_to, contains, does_not_contain ]
+                  enum: [equal_to, not_equal_to, contains, does_not_contain]
                 values:
                   type: array
                   items:
@@ -36,23 +37,27 @@ parameters:
                 query_operator:
                   type: string
                   description: query operator name
-                enum: [ AND, OR ]
+                  enum: [AND, OR]
             example:
               - attribute_key: 'browser_language'
-              filter_operator: 'not_eq'
+                filter_operator: 'not_equal_to'
                 values: ['en']
                 query_operator: 'AND'
               - attribute_key: 'status'
-              filter_operator: 'eq'
+                filter_operator: 'equal_to'
                 values: ['pending']
                 query_operator: null
 
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/conversation_list'
+          $ref: '#/components/schemas/conversation_list'
-  400:
+  '400':
     description: Bad Request Error
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/bad_request_error'
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/conversation/index.yml

@@ -1,5 +1,5 @@
 parameters:
-  - $ref: '#/parameters/account_id'
+  - $ref: '#/components/parameters/account_id'
 
 get:
   tags:
@@ -7,127 +7,83 @@ get:
   operationId: conversationList
   description: List all the conversations with pagination
   summary: Conversations List
+  security:
+    - userApiKey: []
   parameters:
     - name: assignee_type
       in: query
+      schema:
         type: string
         enum: ['me', 'unassigned', 'all', 'assigned']
         default: 'all'
       description: Filter conversations by assignee type.
     - name: status
       in: query
+      schema:
         type: string
         enum: ['all', 'open', 'resolved', 'pending', 'snoozed']
         default: 'open'
       description: Filter by conversation status.
     - name: q
       in: query
+      schema:
         type: string
       description: Filters conversations with messages containing the search term
     - name: inbox_id
       in: query
+      schema:
         type: integer
     - name: team_id
       in: query
+      schema:
         type: integer
     - name: labels
       in: query
+      schema:
         type: array
         items:
           type: string
     - name: page
       in: query
+      schema:
         type: integer
         default: 1
       description: paginate through conversations
 
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/conversation_list'
+            $ref: '#/components/schemas/conversation_list'
-    400:
+    '400':
       description: Bad Request Error
+      content:
+        application/json:
           schema:
-        $ref: '#/definitions/bad_request_error'
+            $ref: '#/components/schemas/bad_request_error'
 
 post:
   tags:
     - Conversations
   operationId: newConversation
   summary: Create New 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"
+  description: "Creating a conversation in chatwoot requires a source id. \n\n Learn more about source_id: https://www.chatwoot.com/hc/user-guide/articles/1677839703-how-to-create-an-api-channel-inbox#send-messages-to-the-api-channel"
   security:
     - userApiKey: []
     - agentBotApiKey: []
-  parameters:
+  requestBody:
-    - name: data
-      in: body
     required: true
-      schema:
-        type: object
-        required:
-          - source_id
-          - inbox_id
-        properties:
-          source_id:
-            type: string
-            description: Conversation source id
-          inbox_id:
-            type: string
-            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
-          custom_attributes:
-            type: object
-            description: The object to save custom attributes for conversation, accepts custom attributes key and value
-            example: { attribute_key: attribute_value, priority_conversation_number: 3 }
-          status:
-            type: string
-            enum: ['open', 'resolved', 'pending']
-            description: Specify the conversation whether it's pending, open, closed
-          assignee_id:
-            type: string
-            description: Agent Id for assigning a conversation to an agent
-          team_id:
-            type: string
-            description: Team Id for assigning a conversation to a team
-          message:
-            type: object
-            description: The initial message to be sent to the conversation
-            required: ['content']
-            properties:
     content:
-                type: string
+      application/json:
-                description: The content of the message
+        schema:
-              template_params:
+          $ref: '#/components/schemas/conversation_create_payload'
-                type: object
-                description: The template params for the message in case of whatsapp Channel
-                properties:
-                  name:
-                    type: string
-                    description: Name of the template
-                    example: 'sample_issue_resolution'
-                  category:
-                    type: string
-                    description: Category of the template
-                    example: UTILITY
-                  language:
-                    type: string
-                    description: Language of the template
-                    example: en_US
-                  processed_params: 
-                    type: object
-                    description: The processed param values for template variables in template
-                    example: 
-                      1: "Chatwoot"
   responses:
-    200:
+    '200':
       description: Success
+      content:
+        application/json:
           schema:
             type: object
             properties:
@@ -140,5 +96,9 @@ post:
               inbox_id:
                 type: number
                 description: ID of the inbox
-    403:
+    '403':
       description: Access denied
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/conversation/labels/create.yml

@@ -1,26 +1,41 @@
 tags:
-  - Conversation Labels
+  - Conversations
 operationId: conversation-add-labels
 summary: Add Labels
+security:
+  - userApiKey: []
 description: Add labels to a conversation. Note that this API would overwrite the existing list of labels associated to the conversation.
-parameters:
+requestBody:
-  - name: data
-    in: body
   required: true
+  content:
+    application/json:
       schema:
         type: object
+        required:
+          - labels
         properties:
           labels:
             type: array
             description: Array of labels (comma-separated strings)
             items:
               type: string
+            example: ['support', 'billing']
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/conversation_labels'
+          $ref: '#/components/schemas/conversation_labels'
-  404:
+  '404':
     description: Conversation not found
-  401:
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '401':
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/conversation/labels/index.yml

@@ -1,14 +1,26 @@
 tags:
-  - Conversation Labels
+  - Conversations
 operationId: list-all-labels-of-a-conversation
 summary: List Labels
+security:
+  - userApiKey: []
 description: Lists all the labels of a conversation
 responses:
-  200:
+  '200':
     description: Success
+    content:
+      application/json:
         schema:
-      $ref: '#/definitions/conversation_labels'
+          $ref: '#/components/schemas/conversation_labels'
-  404:
+  '404':
     description: Conversation not found
-  401:
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '401':
     description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'