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
@@ -35,8 +44,8 @@ properties:
         type: string
         description: Language of the template
         example: en_US
-      processed_params: 
+      processed_params:
         type: object
         description: The processed param values for template variables in template
-        example: 
+        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.
+    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
+    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
+    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

@@ -19,14 +19,13 @@ properties:
     enum: ['agent', 'administrator']
   confirmed:
     type: boolean
-  availability_status: 
+  availability_status:
     type: string
     enum: ['available', 'busy', 'offline']
     description: The availability status of the agent computed by Chatwoot.
   auto_offline:
     type: boolean
     description: Whether the availability status of agent is configured to go offline automatically when away.
-  custom_attributes: 
+  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/contact.yml

@@ -1,5 +1,5 @@
 type: object
-properties: 
+properties:
   id:
     type: integer
     description: Id of the contact
@@ -14,4 +14,4 @@ properties:
     description: Email of the contact
   pubsub_token:
     type: string
-    description: The token to be used to connect to chatwoot websocket
+    description: The token to be used to connect to chatwoot websocket

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

@@ -19,10 +19,10 @@ properties:
     enum: ['agent', 'administrator']
   confirmed:
     type: boolean
-  custom_attributes: 
+  custom_attributes:
     type: object
     description: Available for users who are created through platform APIs and has custom attributes associated.
   accounts:
     type: array
     items:
-      $ref: '#/definitions/account'
+      $ref: '#/components/schemas/account'

swagger/index.yml

@@ -1,47 +1,39 @@
-swagger: "2.0"
+openapi: '3.0.4'
 info:
-  description: This is the API documentation for Chatwoot server.
-  version: 1.0.0
   title: Chatwoot
-  termsOfService:	https://www.chatwoot.com/terms-of-service/
+  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:
-  - https
-produces:
-- application/json; charset=utf-8
-consumes:
-- application/json; charset=utf-8
-securityDefinitions:
-  userApiKey:
-    type: apiKey
-    in: header
-    name: api_access_token
-    description: This token can be obtained by visiting the profile page or via rails console. Provides access to  endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.
-  agentBotApiKey:
-    type: apiKey
-    in: header
-    name: api_access_token
-    description: This token should be provided by system admin or obtained via rails console. This token can be used to build bot integrations and can only access limited apis.
-  platformAppApiKey:
-    type: apiKey
-    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:
+components:
-  $ref: ./definitions/index.yml
+  schemas:
-parameters:
+    $ref: ./definitions/index.yml
-  $ref: ./parameters/index.yml
+  parameters:
+    $ref: ./parameters/index.yml
+  securitySchemes:
+    userApiKey:
+      type: apiKey
+      in: header
+      name: api_access_token
+      description: This token can be obtained by visiting the profile page or via rails console. Provides access to  endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.
+    agentBotApiKey:
+      type: apiKey
+      in: header
+      name: api_access_token
+      description: This token should be provided by system admin or obtained via rails console. This token can be used to build bot integrations and can only access limited apis.
+    platformAppApiKey:
+      type: apiKey
+      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.
 
 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,14 +1,15 @@
 in: query
 name: sort
-type: string
+schema:
-enum:
+  type: string
-  - name
+  enum:
-  - email
+    - name
-  - phone_number
+    - email
-  - last_activity_at
+    - phone_number
-  - -name
+    - last_activity_at
-  - -email
+    - -name
-  - -phone_number
+    - -email
-  - -last_activity_at
+    - -phone_number
+    - -last_activity_at
 required: false
 description: The attribute by which list should be sorted

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,12 +1,13 @@
 in: query
 name: metric
-type: string
+schema:
-enum:
+  type: string
-  - conversations_count
+  enum:
-  - incoming_messages_count
+    - conversations_count
-  - outgoing_messages_count
+    - incoming_messages_count
-  - avg_first_response_time
+    - outgoing_messages_count
-  - avg_resolution_time
+    - avg_first_response_time
-  - resolutions_count
+    - avg_resolution_time
+    - resolutions_count
 required: true
 description: The type of metric

swagger/parameters/report_type.yml

@@ -1,11 +1,12 @@
 in: query
 name: type
-type: string
+schema:
-enum:
+  type: string
-  - account
+  enum:
-  - agent
+    - account
-  - inbox
+    - agent
-  - label
+    - inbox
-  - team
+    - label
+    - team
 required: true
 description: Type of report

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
-    required: true
+  content:
-    schema:
+    application/json:
-      $ref: '#/definitions/agent_bot_create_update_payload'
+      schema:
+        $ref: '#/components/schemas/agent_bot_create_update_payload'
 responses:
-  200:
+  '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/agent_bot'
+      application/json:
-  401:
+        schema:
+          $ref: '#/components/schemas/agent_bot'
+  '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
-    schema:
+    content:
-      type: array
+      application/json:
-      description: 'Array of agent bots'
+        schema:
-      items:
+          type: array
-        $ref: '#/definitions/agent_bot'
+          description: 'Array of agent bots'
-
+          items:
-  401:
+            $ref: '#/components/schemas/agent_bot'
+  '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
-    schema:
+    content:
-      $ref: '#/definitions/agent_bot'
+      application/json:
-  401:
+        schema:
+          $ref: '#/components/schemas/agent_bot'
+  '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
+  required: true
-    schema:
+  content:
-      $ref: '#/definitions/agent_bot_create_update_payload'
+    application/json:
+      schema:
+        $ref: '#/components/schemas/agent_bot_create_update_payload'
 responses:
-  200:
+  '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/agent_bot'
+      application/json:
-  401:
+        schema:
+          $ref: '#/components/schemas/agent_bot'
+  '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
+  required: true
-    in: body
+  content:
-    required: true
+    application/json:
-    schema:
+      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
-    schema:
+    content:
-        description: 'Newly Created Agent'
+      application/json:
-        $ref: '#/definitions/agent'
+        schema:
-  403:
+          description: 'Newly Created Agent'
+          $ref: '#/components/schemas/agent'
+  '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
-    type: integer
+    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
-    schema:
+    content:
-        type: array
+      application/json:
-        description: 'Array of all active agents'
+        schema:
-        items:
+          type: array
-          $ref: '#/definitions/agent'
+          description: 'Array of all active agents'
+          items:
+            $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
-    type: integer
+    schema:
+      type: integer
     required: true
     description: The ID of the agent to be updated.
-  - name: data
+requestBody:
-    in: body
+  required: true
-    required: true
+  content:
-    schema:
+    application/json:
-      type: object
+      schema:
-      required:
+        $ref: '#/components/schemas/agent_update_payload'
-        - 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
-    schema:
+    content:
-        description: 'The updated agent'
+      application/json:
-        $ref: '#/definitions/agent'
+        schema:
+          description: 'The updated 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
+  required: true
-    in: body
+  content:
-    required: true
+    application/json:
-    schema:
+      schema:
-      $ref: '#/definitions/article_create_update_payload'
+        $ref: '#/components/schemas/article_create_update_payload'
 responses:
   '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/article'
+      application/json:
+        schema:
+          $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
+  required: true
-    in: body
+  content:
-    required: true
+    application/json:
-    schema:
+      schema:
-      $ref: '#/definitions/automation_rule_create_update_payload'
+        $ref: '#/components/schemas/automation_rule_create_update_payload'
 responses:
   '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/automation_rule'
+      application/json:
+        schema:
+          $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,7 +8,8 @@ security:
 parameters:
   - in: path
     name: id
-    type: integer
+    schema:
+      type: integer
     required: true
     description: The ID of the automation rule to be deleted
 responses:
@@ -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
-    schema:
+    content:
-      type: array
+      application/json:
-      description: Array of all automation rules
+        schema:
-      items:
+          type: array
-        $ref: '#/definitions/automation_rule'
+          description: Array of all automation rules
+          items:
+            $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
-    type: integer
+    schema:
+      type: integer
     required: true
     description: The ID of the automation rule to be updated.
 responses:
   '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/automation_rule'
+      application/json:
+        schema:
+          $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
-    type: integer
+    schema:
+      type: integer
     required: true
     description: The ID of the automation rule to be updated.
-  - name: data
+requestBody:
-    in: body
+  required: true
-    required: true
+  content:
-    schema:
+    application/json:
-      $ref: '#/definitions/automation_rule_create_update_payload'
+      schema:
+        $ref: '#/components/schemas/automation_rule_create_update_payload'
 responses:
   '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/automation_rule'
+      application/json:
+        schema:
+          $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
+  required: true
-    in: body
+  content:
-    required: true
+    application/json:
-    schema:
+      schema:
-      $ref: '#/definitions/canned_response_create_update_payload'
+        $ref: '#/components/schemas/canned_response_create_update_payload'
 responses:
-  200:
+  '200':
     description: Success
-    schema:
+    content:
-        description: 'Newly Created Canned Response'
+      application/json:
-        $ref: '#/definitions/canned_response'
+        schema:
-  403:
+          description: 'Newly Created Canned Response'
+          $ref: '#/components/schemas/canned_response'
+  '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
-    type: integer
+    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
-    schema:
+    content:
-        type: array
+      application/json:
-        description: 'Array of all canned responses'
+        schema:
-        items:
+          type: array
-          $ref: '#/definitions/canned_response'
+          description: 'Array of all canned responses'
-  403:
+          items:
+            $ref: '#/components/schemas/canned_response'
+  '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
-    type: integer
+    schema:
+      type: integer
     required: true
     description: The ID of the canned response to be updated.
-  - name: data
+requestBody:
-    in: body
+  required: true
-    required: true
+  content:
-    schema:
+    application/json:
-      $ref: '#/definitions/canned_response_create_update_payload'
+      schema:
+        $ref: '#/components/schemas/canned_response_create_update_payload'
 responses:
-  200:
+  '200':
     description: Success
-    schema:
+    content:
-        description: 'The updated canned response'
+      application/json:
-        $ref: '#/definitions/canned_response'
+        schema:
-  404:
+          description: 'The updated canned response'
+          $ref: '#/components/schemas/canned_response'
+  '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
+  required: true
-    in: body
+  content:
-    required: true
+    application/json:
-    schema:
+      schema:
-      $ref: '#/definitions/category_create_update_payload'
+        $ref: '#/components/schemas/category_create_update_payload'
 responses:
   '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/category'
+      application/json:
+        schema:
+          $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,34 +5,47 @@ 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
-      type: number
+      schema:
+        type: number
       description: ID of the contact
       required: true
-    - name: data
+  security:
-      in: body
+    - userApiKey: []
-      required: true
+  requestBody:
-      schema:
+    required: true
-        type: object
+    content:
-        required:
+      application/json:
-          - inbox_id
+        schema:
-        properties:
+          type: object
-          inbox_id:
+          required:
-            type: number
+            - inbox_id
-            description: The ID of the inbox
+          properties:
-          source_id:
+            inbox_id:
-            type: string
+              type: number
-            description: Contact Inbox Source Id
+              description: The ID of the inbox
+              example: 1
+            source_id:
+              type: string
+              description: Contact Inbox Source Id
   responses:
-    200:
+    '200':
       description: Success
-      schema:
+      content:
-        $ref: '#/definitions/contact_inboxes'
+        application/json:
-    401:
+          schema:
+            $ref: '#/components/schemas/contact_inboxes'
+    '401':
       description: Authentication error
-      schema:
+      content:
-        $ref: '#/definitions/bad_request_error'
+        application/json:
-    422:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '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
-      type: number
+      schema:
+        type: number
       description: ID of the contact
       required: true
   responses:
-    200:
+    '200':
       description: Success
-      schema:
+      content:
-        $ref: '#/definitions/contactable_inboxes'
+        application/json:
-    401:
+          schema:
+            $ref: '#/components/schemas/contactable_inboxes'
+    '401':
       description: Authentication error
-      schema:
+      content:
-        $ref: '#/definitions/bad_request_error'
+        application/json:
-    422:
+          schema:
+            $ref: '#/components/schemas/bad_request_error'
+    '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
-      type: number
-      description: ID of the contact
       required: true
-  responses:
-    200:
-      description: Success
       schema:
-        $ref: '#/definitions/contact_conversations'
+        type: number
-    404:
+      description: ID of the contact
+  security:
+    - userApiKey: []
+  responses:
+    '200':
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/contact_conversations'
+    '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
-    type: number
-    description: ID of the contact
     required: true
+    schema:
+      type: number
+    description: ID of the contact
 
 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
-      schema:
+      content:
-        $ref: '#/definitions/extended_contact'
+        application/json:
-    404:
+          schema:
+            $ref: '#/components/schemas/extended_contact'
+    '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
+    required: true
-      in: body
+    content:
-      required: true
+      application/json:
-      schema:
+        schema:
-        $ref: '#/definitions/contact_update'
+          $ref: '#/components/schemas/contact_update_payload'
   responses:
-    204:
+    '204':
       description: Success
-      schema:
+      content:
-        $ref: '#/definitions/contact_base'
+        application/json:
-    404:
+          schema:
+            $ref: '#/components/schemas/contact_base'
+    '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,58 +1,64 @@
-tags:
+post:
-  - Contacts
+  tags:
-operationId: contactFilter
+    - Contacts
-description: Filter contacts with custom filter options and pagination
+  operationId: contactFilter
-summary: Contact Filter
+  description: Filter contacts with custom filter options and pagination
-security:
+  summary: Contact Filter
-  - userApiKey: []
+  security:
-  - agentBotApiKey: []
+    - userApiKey: []
-parameters:
+  parameters:
-  - name: page
+    - $ref: '#/components/parameters/account_id'
-    in: query
+    - name: page
-    type: integer
+      in: query
-  - name: body
+      schema:
-    in: body
+        type: number
+  requestBody:
     required: true
-    schema:
+    content:
-      type: object
+      application/json:
-      properties:
+        schema:
-        payload:
+          type: object
-          type: array
+          properties:
-          items:
+            payload:
-            type: object
+              type: array
-            properties:
+              items:
-              attribute_key:
+                type: object
-                type: string
+                properties:
-                description: filter attribute name
+                  attribute_key:
-              filter_operator:
+                    type: string
-                type: string
+                    description: filter attribute name
-                description: filter operator name
+                  filter_operator:
-                enum: [ equal_to, not_equal_to, contains, does_not_contain ]
+                    type: string
-              values:
+                    description: filter operator name
-                type: array
+                    enum: [equal_to, not_equal_to, contains, does_not_contain]
-                items:
+                  values:
-                  type: string
+                    type: array
-                description: array of the attribute values to filter
+                    items:
-              query_operator:
+                      type: string
-                type: string
+                    description: array of the attribute values to filter
-                description: query operator name
+                  query_operator:
-                enum: [ AND, OR ]
+                    type: string
-          example:
+                    description: query operator name
-            - attribute_key: 'name'
+                    enum: [AND, OR]
-              filter_operator: 'equal_to'
+              example:
-              values: ['en']
+                - attribute_key: 'name'
-              query_operator: 'AND'
+                  filter_operator: 'equal_to'
-            - attribute_key: 'country_code'
+                  values: ['en']
-              filter_operator: 'equal_to'
+                  query_operator: 'AND'
-              values: ['us']
+                - attribute_key: 'country_code'
-              query_operator: null
+                  filter_operator: 'equal_to'
-
+                  values: ['us']
-responses:
+                  query_operator: null
-  200:
+  responses:
-    description: Success
+    '200':
-    schema:
+      description: Success
-      $ref: '#/definitions/contact_list'
+      content:
-  400:
+        application/json:
-    description: Bad Request Error
+          schema:
-    schema:
+            $ref: '#/components/schemas/contact_list'
-      $ref: '#/definitions/bad_request_error'
+    '400':
+      description: Bad Request Error
+      content:
+        application/json:
+          schema:
+            $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
-      schema:
+      content:
-        $ref: '#/definitions/contact_list'
+        application/json:
-    400:
+          schema:
+            $ref: '#/components/schemas/contact_list'
+    '400':
       description: Bad Request Error
-      schema:
+      content:
-        $ref: '#/definitions/bad_request_error'
+        application/json:
+          schema:
+            $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
-      required: true
+    content:
-      schema:
+      application/json:
-        $ref: '#/definitions/contact_create'
+        schema:
+          $ref: '#/components/schemas/contact_create_payload'
   responses:
-    200:
+    '200':
       description: Success
-      schema:
+      content:
-        $ref: '#/definitions/extended_contact'
+        application/json:
-    400:
+          schema:
+            $ref: '#/components/schemas/extended_contact'
+    '400':
       description: Bad Request Error
-      schema:
+      content:
-        $ref: '#/definitions/bad_request_error'
+        application/json:
+          schema:
+            $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
-      type: string
+      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
-      schema:
+      content:
-        type: object
+        application/json:
-        properties:
+          schema:
-          payload:
+            type: object
-            $ref: '#/definitions/contact_list'
+            properties:
-    401:
+              payload:
+                $ref: '#/components/schemas/contact_list'
+    '401':
       description: Authentication error
-      schema:
+      content:
-        $ref: '#/definitions/bad_request_error'
+        application/json:
+          schema:
+            $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
+  required: true
-    in: body
+  content:
-    required: true
+    application/json:
-    schema:
+      schema:
-      type: object
+        type: object
-      properties:
+        properties:
-        assignee_id:
+          assignee_id:
-          type: number
+            type: number
-          description: Id of the assignee user
+            description: Id of the assignee user
-        team_id:
+            example: 1
-          type: number
+          team_id:
-          description: Id of the team. If the assignee_id is present, this param would be ignored
+            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
-    schema:
+    content:
-      $ref: '#/definitions/user'
+      application/json:
-  404:
+        schema:
-    description: Conversation not found
+          $ref: '#/components/schemas/user'
-  401:
+  '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,32 +5,41 @@ summary: Update Custom Attributes
 description: Updates the custom attributes of a conversation
 security:
   - userApiKey: []
-  - agentBotApiKey: []
+requestBody:
-parameters:
+  required: true
-  - name: data
+  content:
-    in: body
+    application/json:
-    required: true
+      schema:
-    schema:
+        type: object
-      type: object
+        required:
-      required:
+          - custom_attributes
-        - custom_attributes
+        properties:
-      properties:
+          custom_attributes:
-        custom_attributes:
+            type: object
-          type: object
+            description: The custom attributes to be set for the conversation
-          description: The custom attributes to be set for the conversation
+            example:
-          example:
+              order_id: '12345'
-            order_id: "12345"
+              previous_conversation: '67890'
-            previous_conversation: "67890"
 responses:
-  200:
+  '200':
     description: Success
-    schema:
+    content:
-      type: object
+      application/json:
-      properties:
+        schema:
-        custom_attributes:
           type: object
-          description: The custom attributes of the conversation
+          properties:
-  404:
+            custom_attributes:
+              type: object
+              description: The custom attributes of the conversation
+  '401':
+    description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '404':
     description: Conversation not found
-  401:
+    content:
-    description: Unauthorized 
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/application/conversation/filter.yml

@@ -5,54 +5,59 @@ description: Filter conversations with custom filter options and pagination
 summary: Conversations Filter
 security:
   - userApiKey: []
-  - agentBotApiKey: []
 parameters:
   - name: page
     in: query
-    type: integer
-  - name: body
-    in: body
-    required: true
     schema:
-      type: object
+      type: number
-      properties:
+requestBody:
-        payload:
+  required: true
-          type: array
+  content:
-          items:
+    application/json:
-            type: object
+      schema:
-            properties:
+        type: object
-              attribute_key:
+        properties:
-                type: string
+          payload:
-                description: filter attribute name
+            type: array
-              filter_operator:
+            items:
-                type: string
+              type: object
-                description: filter operator name
+              properties:
-                enum: [ equal_to, not_equal_to, contains, does_not_contain ]
+                attribute_key:
-              values:
-                type: array
-                items:
                   type: string
-                description: array of the attribute values to filter
+                  description: filter attribute name
-              query_operator:
+                filter_operator:
-                type: string
+                  type: string
-                description: query operator name
+                  description: filter operator name
-                enum: [ AND, OR ]
+                  enum: [equal_to, not_equal_to, contains, does_not_contain]
-          example:
+                values:
-            - attribute_key: 'browser_language'
+                  type: array
-              filter_operator: 'not_eq'
+                  items:
-              values: ['en']
+                    type: string
-              query_operator: 'AND'
+                  description: array of the attribute values to filter
-            - attribute_key: 'status'
+                query_operator:
-              filter_operator: 'eq'
+                  type: string
-              values: ['pending']
+                  description: query operator name
-              query_operator: null
+                  enum: [AND, OR]
+            example:
+              - attribute_key: 'browser_language'
+                filter_operator: 'not_equal_to'
+                values: ['en']
+                query_operator: 'AND'
+              - attribute_key: 'status'
+                filter_operator: 'equal_to'
+                values: ['pending']
+                query_operator: null
 
 responses:
-  200:
+  '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/conversation_list'
+      application/json:
-  400:
+        schema:
+          $ref: '#/components/schemas/conversation_list'
+  '400':
     description: Bad Request Error
-    schema:
+    content:
-      $ref: '#/definitions/bad_request_error'
+      application/json:
+        schema:
+          $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,138 +7,98 @@ get:
   operationId: conversationList
   description: List all the conversations with pagination
   summary: Conversations List
+  security:
+    - userApiKey: []
   parameters:
     - name: assignee_type
       in: query
-      type: string
+      schema:
-      enum: ['me', 'unassigned', 'all', 'assigned']
+        type: string
-      default: 'all'
+        enum: ['me', 'unassigned', 'all', 'assigned']
+        default: 'all'
       description: Filter conversations by assignee type.
     - name: status
       in: query
-      type: string
+      schema:
-      enum: ['all', 'open', 'resolved', 'pending', 'snoozed']
+        type: string
-      default: 'open'
+        enum: ['all', 'open', 'resolved', 'pending', 'snoozed']
+        default: 'open'
       description: Filter by conversation status.
     - name: q
       in: query
-      type: string
+      schema:
+        type: string
       description: Filters conversations with messages containing the search term
     - name: inbox_id
       in: query
-      type: integer
+      schema:
+        type: integer
     - name: team_id
       in: query
-      type: integer
+      schema:
+        type: integer
     - name: labels
       in: query
-      type: array
+      schema:
-      items:
+        type: array
-        type: string
+        items:
+          type: string
     - name: page
       in: query
-      type: integer
+      schema:
-      default: 1
+        type: integer
+        default: 1
       description: paginate through conversations
 
   responses:
-    200:
+    '200':
       description: Success
-      schema:
+      content:
-        $ref: '#/definitions/conversation_list'
+        application/json:
-    400:
+          schema:
+            $ref: '#/components/schemas/conversation_list'
+    '400':
       description: Bad Request Error
-      schema:
+      content:
-        $ref: '#/definitions/bad_request_error'
+        application/json:
+          schema:
+            $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
+    required: true
-      in: body
+    content:
-      required: true
+      application/json:
-      schema:
+        schema:
-        type: object
+          $ref: '#/components/schemas/conversation_create_payload'
-        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
-                description: The content of the message
-              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"
   responses:
-    200:
+    '200':
       description: Success
-      schema:
+      content:
-        type: object
+        application/json:
-        properties:
+          schema:
-          id:
+            type: object
-            type: number
+            properties:
-            description: ID of the conversation
+              id:
-          account_id:
+                type: number
-            type: number
+                description: ID of the conversation
-            description: Account Id
+              account_id:
-          inbox_id:
+                type: number
-            type: number
+                description: Account Id
-            description: ID of the inbox
+              inbox_id:
-    403:
+                type: number
+                description: ID of the inbox
+    '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
+  required: true
-    in: body
+  content:
-    required: true
+    application/json:
-    schema:
+      schema:
-      type: object
+        type: object
-      properties:
+        required:
-        labels:
+          - labels
-          type: array
+        properties:
-          description: Array of labels (comma-separated strings)
+          labels:
-          items:
+            type: array
-            type: string
+            description: Array of labels (comma-separated strings)
+            items:
+              type: string
+            example: ['support', 'billing']
 responses:
-  200:
+  '200':
     description: Success
-    schema:
+    content:
-      $ref: '#/definitions/conversation_labels'
+      application/json:
-  404:
+        schema:
+          $ref: '#/components/schemas/conversation_labels'
+  '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'