Help Center JSON Schema Reference

Help center schema provides a structured approach to organizing content using a JSON schema. It enables content to be organized into categories and pages, with support for various interactive elements.

This reference documents the schema used by the Advanced editor's JSON upload/text editor. The fields available in the Visual editor map directly to these same fields.

Schema Structure

The help center schema uses a hierarchical structure:

The root object contains schema version and a list of categories
Each category contains the category information and a list of pages
Each page contains the page information with content organized into body and footer sections
Content sections contain various element types (markdown, buttons, links, etc.)

Schema Version

{
  "schema_version": "1",
  "categories": [...]
}

Always include the schema_version field at the root level. Currently, "1" is the only supported version.

Field	Type	Description	Required	Remarks
schema_version	string	Version of the schema	Yes	Must be "1" (currently, no other version exist)
categories	array	List of help pages in this category	Yes	Max 200 categories

Field	Type	Description	Required	Remarks
title	string	Display name for thecategory	Yes	Max char. 100
key	string	Unique identifier for thecategory (alphanumerics & hyphens only)	Yes	Max char. 100, only alphabet and numeric, use - as space
description	string	Brief description of thecategory	Yes	Max char. 255
pages	array	List of help pages in thiscategory	Yes	Max 500 pages

Pages

Pages are individual help articles or content pieces within a category.

"pages": [
  {
    "key": "how-to-reset-password",
    "include_on_root": true,
    "title": "How to Reset Your Password",
    "description": "Learn how to securely reset your password if you've forgotten it.",
    "body": "",
    "footer": ""
  }
]

Field	Type	Description	Required	Remarks
key	string	Unique identifier for thepage (alphanumerics & hyphens only)	Yes	Max char. 100, only alphabet and numeric, use - as space
include_on_root	boolean	Whether to show this page on the main help center page	No	Defaults to false if not provided.
title	string	Display name for thepage	Yes	Max char. 100
description	string	Brief description of thecategory	Yes	Max char. 255
body	object	Container for the main content elements	Yes
footer	object	Container for footer elements (optional)	No

Content Sections

Both body and footer objects contain an elements array with the content components.

"body": {
  "elements": [...]
}

"footer": {
  "elements": [...]
}

Field	Type	Description	Required	Remarks
elements	object	The elements on the page's body or footer	No	Max elements 500

Element Types

Markdown

For text content with formatting support.

{
  "type": "MARKDOWN",
  "content": "If you've forgotten your password, follow these steps to reset it: \n\n1. Go to the login page. \n2. Click on 'Forgot Password?'. \n3. Enter your registered email address..."
}

Field	Type	Description	Required	Remarks
type	string	Must be "MARKDOWN"	Yes
content	string	Markdown-formatted text content	Yes	Max char. 10,000

Help Center Page Link

For linking to other pages within the help center.

{
  "type": "HELP_CENTER_PAGE_LINK",
  "page_key": "how-to-delete-account"
}

Field	Type	Description	Required
type	string	Must be "HELP_CENTER_PAGE_LINK"	Yes
page_key	string	Key of the page to link to	Yes

Iframe

For embedding your own website page.

{
  "type": "IFRAME",
  "url": "https://youriframeurl.com/path",
  "propagate_data": false,
  "height": "600px"
}

Field	Type	Description	Required	Remarks
type	string	Must be "IFRAME"	Yes
url	string	The src URL of your Iframe	Yes	Max char. 1000
propagate_data	bool	Allow sending data to iframevia query param	No	See note in document
height	string	Height of the iframe	No
sandbox	string	Same as HTML sandboxattribute	No	Max char. 200

Button

Interactive element for actions.

Field	Type	Description	Required
type	string	Must be "BUTTON"	Yes
action	string	Action type (currently, there's only "START_CONVERSATION")	Yes
label	object	Contains label to display on the button	Yes
metadata	object	Action-specific data	No*

*metadata requirements may differ for different actions

Label Metadata

Field	Type	Description	Required	Remarks
text	string	Text on the button	Yes	Max char. 100

START_CONVERSATION Metadata

Field	Type	Description	Required	Remarks
topic_keys	array of string	Topic keys for prechatform	No	Max 20 keys

Complete Schema Example

Here's a minimal example showing the essential structure:

{
  "schema_version": "1",
  "categories": [
    {
      "type": "HELP_CENTER_CATEGORY",
      "title": "Category Title",
      "key": "category-key",
      "description": "Category description",
      "pages": [
        {
          "type": "HELP_CENTER_PAGE",
          "key": "page-key",
          "include_on_root": true,
          "title": "Page Title",
          "description": "Page description",
          "body": {
            "elements": [
              {
                "type": "MARKDOWN",
                "content": "Markdown content goes here"
              }
            ]
          }
        }
      ]
    }
  ]
}

Validation Rules

All keys (categories and pages) must be unique
All page_key references must point to existing pages
All required fields must be provided

Simple Example

You can use this simple example for testing purposes, but please change the topic_keys to correct topics keys that exist on your workspace.

{
  "schema_version": "1",
  "categories": [
    {
      "title": "Account Management",
      "key": "account-management",
      "description": "How to manage your account",
      "pages": [
        {
          "key": "how-to-reset-password",
          "include_on_root": true,
          "title": "How to Reset Your Password",
          "description": "Learn how to securely reset your password if you've forgotten it.",
          "body": {
            "elements": [
              {
                "type": "MARKDOWN",
                "content": "If you've forgotten your password, follow these steps to reset it: \n\n1. Go to the login page. \n2. Click on 'Forgot Password?'. \n3. Enter your registered email address. \n4. Check your email for the reset link. \n5. Follow the instructions to set a new password."
              },
              {
                "type": "MARKDOWN",
                "content": "Need to delete your account instead? Learn more here:"
              },
              {
                "type": "HELP_CENTER_PAGE_LINK",
                "page_key": "how-to-delete-account"
              }
            ]
          },
          "footer": {
            "elements": [
              {
                "type": "BUTTON",
                "action": "START_CONVERSATION",
                "label": {
                  "text": "Chat with Us for Details"
                },
                "metadata": {
                  "topic_keys": ["<YOUR TOPIC KEY>"]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Help Center Schema