fix: Help center api doc (chatwoot#7189)

swagger/definitions/index.yml

@@ -18,6 +18,16 @@ custom_attribute:
  $ref: ./resource/custom_attribute.yml
 automation_rule:
  $ref: ./resource/automation_rule.yml
+portal:
+ $ref: ./resource/portal.yml
+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:
@@ -110,6 +120,14 @@ integrations_hook_update_payload:
 automation_rule_create_update_payload:
  $ref: ./request/automation_rule/create_update_payload.yml
 
+# Help Center
+portal_create_update_payload:
+ $ref: ./request/portal/portal_create_update_payload.yml
+category_create_update_payload:
+ $ref: ./request/portal/category_create_update_payload.yml
+article_create_update_payload:
+ $ref: ./request/portal/article_create_update_payload.yml
+
 
 ## public requests
 public_contact_create_update_payload:

swagger/definitions/request/portal/article_create_update_payload.yml

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

swagger/definitions/request/portal/category_create_update_payload.yml

@@ -0,0 +1,28 @@
+type: object
+properties:
+ description:
+ type: string
+ description: Category description
+ locale:
+ type: string
+ description: Category locale
+ example: en/es
+ name:
+ type: string
+ description: Category name
+ slug:
+ type: string
+ description: Category slug
+ position:
+ type: integer
+ description: Category position in the portal list to sort
+ portal_id:
+ type: integer
+ account_id:
+ type: integer
+ associated_category_id:
+ type: integer
+ description: To associate similar categories to each other, e.g same category of product documentation in different languages
+ 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.

swagger/definitions/request/portal/portal_create_update_payload.yml

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

swagger/definitions/resource/article.yml

@@ -0,0 +1,33 @@
+type: object
+properties:
+ id:
+ type: integer
+ content:
+ type: string
+ description: The text content.
+ meta:
+ type: object
+ position:
+ type: integer
+ status:
+ type: integer
+ enum: ['draft', 'published', 'archived']
+ title:
+ type: string
+ slug:
+ type: string
+ views:
+ type: integer
+ portal_id:
+ type: integer
+ account_id:
+ type: integer
+ author_id:
+ type: integer
+ category_id:
+ type: integer
+ folder_id:
+ type: integer
+ associated_article_id:
+ type: integer
+ description: To associate similar articles to each other, e.g to provide the link for the reference.

swagger/definitions/resource/category.yml

@@ -0,0 +1,25 @@
+type: object
+properties:
+ id:
+ type: integer
+ description:
+ type: string
+ description: The text content.
+ locale:
+ type: string
+ name:
+ type: string
+ slug:
+ type: string
+ position:
+ type: integer
+ portal_id:
+ type: integer
+ account_id:
+ type: integer
+ associated_category_id:
+ type: integer
+ description: To associate similar categories to each other, e.g same category of product documentation in different languages
+ 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.

swagger/definitions/resource/portal.yml

@@ -0,0 +1,34 @@
+type: object
+properties:
+ id:
+ type: integer
+ archived:
+ type: boolean
+ color:
+ type: string
+ config:
+ type: object
+ description: Save information about locales, allowed_locales and default portal/help-center locale
+ custom_domain:
+ type: string
+ header_text:
+ type: string
+ description: The text content.
+ homepage_link:
+ type: string
+ name:
+ type: string
+ slug:
+ type: string
+ page_title:
+ type: string
+ account_id:
+ type: integer
+ categories:
+ type: array
+ items:
+ $ref: '#/definitions/category'
+ articles:
+ type: array
+ items:
+ $ref: '#/definitions/article'

swagger/index.yml

@@ -69,6 +69,7 @@ x-tagGroups:
  - Teams
  - Webhooks
  - Automation Rule
+ - Help Center
  - name: Client
  tags:
  - Contacts API

swagger/parameters/portal_id.yml

@@ -0,0 +1,5 @@
+in: path
+name: portal_id
+type: integer
+required: true
+description: The numeric ID of the portal

swagger/paths/application/article/create.yml

@@ -0,0 +1,20 @@
+tags:
+ - Help Center
+operationId: add-new-article-to-account
+summary: Add a new article
+description: Add a new article to portal
+security:
+ - userApiKey: []
+parameters:
+ - name: data
+ in: body
+ required: true
+ schema:
+ $ref: '#/definitions/article_create_update_payload'
+responses:
+ '200':
+ description: Success
+ schema:
+ $ref: '#/definitions/article'
+ '403':
+ description: Access denied

swagger/paths/application/category/create.yml

@@ -0,0 +1,20 @@
+tags:
+ - Help Center
+operationId: add-new-category-to-account
+summary: Add a new category
+description: Add a new category to portal
+security:
+ - userApiKey: []
+parameters:
+ - name: data
+ in: body
+ required: true
+ schema:
+ $ref: '#/definitions/category_create_update_payload'
+responses:
+ '200':
+ description: Success
+ schema:
+ $ref: '#/definitions/category'
+ '403':
+ description: Access denied

swagger/paths/application/portal/create.yml

@@ -0,0 +1,20 @@
+tags:
+ - Help Center
+operationId: add-new-portal-to-account
+summary: Add a new portal
+description: Add a new portal to account
+security:
+ - userApiKey: []
+parameters:
+ - name: data
+ in: body
+ required: true
+ schema:
+ $ref: '#/definitions/portal_create_update_payload'
+responses:
+ '200':
+ description: Success
+ schema:
+ $ref: '#/definitions/portal'
+ '403':
+ description: Access denied

swagger/paths/application/portal/index.yml

@@ -0,0 +1,19 @@
+tags:
+ - Help Center
+operationId: get-portal
+summary: List all portals in an account
+parameters:
+ - $ref: '#/parameters/account_id'
+description: Get details of portals in an Account
+security:
+ - userApiKey: []
+responses:
+ '200':
+ description: Success
+ schema:
+ type: array
+ description: Array of all portals
+ items:
+ $ref: '#/definitions/portal'
+ '403':
+ description: Access denied

swagger/paths/application/portal/update.yml

@@ -0,0 +1,20 @@
+tags:
+ - Help Center
+operationId: update-new-portal-to-account
+summary: update a new portal
+description: update a new portal to account
+security:
+ - userApiKey: []
+parameters:
+ - name: data
+ in: body
+ required: true
+ schema:
+ $ref: '#/definitions/portal_create_update_payload'
+responses:
+ '200':
+ description: Success
+ schema:
+ $ref: '#/definitions/portal'
+ '403':
+ description: Access denied

swagger/paths/index.yml

@@ -245,6 +245,35 @@
  $ref: ./application/automation_rule/delete.yml
 
 
+# Help Center
+/api/v1/accounts/{account_id}/portals:
+ parameters:
+ - $ref: '#/parameters/account_id'
+ post:
+ $ref: ./application/portal/create.yml
+ get:
+ $ref: ./application/portal/index.yml
+ patch:
+ $ref: ./application/portal/update.yml
+
+
+# Help Center category
+/api/v1/accounts/{account_id}/portals/{portal_id}/categories:
+ parameters:
+ - $ref: '#/parameters/account_id'
+ - $ref: '#/parameters/portal_id'
+ post:
+ $ref: ./application/category/create.yml
+
+# Help Center article
+/api/v1/accounts/{account_id}/portals/{portal_id}/articles:
+ parameters:
+ - $ref: '#/parameters/account_id'
+ - $ref: '#/parameters/portal_id'
+ post:
+ $ref: ./application/article/create.yml
+
+
 # Conversations
 /api/v1/accounts/{account_id}/conversations/meta:
  $ref: ./application/conversation/meta.yml