manifest.json

It is one of the required files when creating the widget. It’s a JSON-formatted file that provides metadata associated with the widget. This file includes the widget's name, description, images, version, language files, and different kinds of settings.

Example of the file manifest.json

{
  "widget": {
    "name": "widget.name",
    "description": "widget.description",
    "short_description": "widget.short_description",
    "version": "1.0.1",
    "interface_version": 2,
    "init_once": true,
    "locale": [
      "en",
      "es"
    ],
    "installation": true,
    "support": {
      "link": "https://www.kommo.com",
      "email": "[email protected]"
    }
  },
  "locations": [
    "ccard-1",
    "clist-0",
    "lcard-1",
    "llist-0",
    "settings",
    "digital_pipeline",
    "advanced_settings",
    "salesbot_designer",
    "sms",
    "mobile_card"
  ],
  "tour": {
    "is_tour": true,
    "tour_images": {
      "en": [
            "/images/tour_1_en.png",
            "/images/tour_2_en.png",
            "/images/tour_3_en.png"
          ],
      "es": [
            "/images/tour_1_es.png",
            "/images/tour_2_es.png",
            "/images/tour_3_es.png"
         ]
    },
    "tour_description": "widget.tour_description"
  },
  "settings": {
    "login": {
      "name": "settings.login",
      "type": "text",
      "required": true
    },
    "api_key": {
      "name": "settings.api_key",
      "type": "text",
      "required": true
    },
    "account": {
      "name": "settings.account",
      "type": "text",
      "required": true
    }
  },
  "dp": {
    "settings": {
      "message": {
        "name": "dp.message",
        "type": "text",
        "required": true
      }
    },
    "action_multiple": false,
    "webhook_url": "https://example.com/webhook"
  },
  "advanced": {
    "title": "advanced.title"
  },
  "salesbot_designer": {
    "handler_code": {
      "name": "salesbot.handler_name",
      "settings": {
        "button_title": {
          "name": "salesbot.button_title",
          "type": "text",
          "default_value": "salesbot.button_title_default_value",
          "manual": true
        },
        "button_caption": {
          "name": "salesbot.button_caption",
          "type": "text",
          "default_value": "salesbot.button_caption_default_value",
          "manual": true
        },
        "text": {
          "name": "salesbot.text",
          "type": "text"
        },
        "number": {
          "name": "salesbot.number",
          "type": "numeric"
        },
        "url": {
          "name": "salesbot.url",
          "type": "url"
        }
      }
    }
  },
  "sms": { 
    "endpoint": "https://example.com/sms_endpoint" 
  },
  "mobile": { 
    "frame_url": "https://example.com/", 
    "color": "#ffff00" 
   }
}

πŸ“˜

If the widget is developed for use in multiple languages, the corresponding i18n folder files must contain values in the format "widget.name", "widget.description", "advanced.title", etc.

Properties of the file manifest.json

The properties of this file are in this table

ParameterRequired?Data typeDescription
widgetβœ…objThis block contains all the basic settings of the widget.
widget/nameβœ…stringThe name of the widget to be included in the widget list. The value "widget.name"means that it will be taken from the corresponding i18n folder file, depending on the localization.
If the widget is uploaded to a public integration, the name specified in the integration will be used, but the field is still mandatory.
widget/descriptionβœ…stringThe description of the widget can be found in the widget settings window. It should contain the path to the translation in the language files. You can use HTML tags and special short tags to create a personalized description. For instance, if you need to show the subdomain of the Kommo account in which the user works, you can use the #SUBDOMAIN# tag.

Here's a list of available tags:
#HOST# shows the current host;
#SUBDOMAIN# shows the account subdomain;
#LOGIN# displays the login of the current authorized user;
#ACCOUNT_ID# shows the ID of the current account in the system;
#USER_ID# displays the ID of the current user on the system;
#TOP_LEVEL_DOMAIN# shows the top-level domain (com).
If the widget is uploaded to a public integration, the description specified in the integration will be used. However, this field is still mandatory.
widget/short_descriptionβœ…stringA brief description of the widget's functionality will be displayed on the left side of the modal window.
widget/version❌stringThe widget version field is for informational purposes and should be updated every time you upload the widget archive to ensure that the files in the system are up-to-date.
widget/interface_versionβœ…intThe interface version field specifies the system interface widget's loaded version, and it should be set to 2.
widget/init_once❌boolThe widget/init_once field controls the ability to call the init() and bind_actions() functions once per session. Setting it to true or false depends on the widget's functionality. For instance, VoIP widgets keep the WebSocket connection constant, so widget/init_once should be set to true. If there is no common context for all pages, then it’s better to set the value to false.
widget/localeβœ…arrayTo allow for the widget to be available in multiple languages, an array of language codes should be provided and each language code should correspond to a translation file in the i18n folder. The available language options are English (en), Spanish (es), and Portuguese (pt).
When publishing a widget on the Kommo Marketplace, the language files must match the languages that are filled in the integration. Additionally, you must provide support in the available languages.
widget/installationβœ…boolThe "settings" option for the widget can be set to true or false. If set to true, settings will appear during installation. If set to false, the widget will only appear in the widget list without asking for settings or installations. This is usually the case when all settings are managed in another system that interacts with Kommo via the API.
widget/support❌objA set of the widget support information.
support/link❌stringYou must provide a valid and functional link to the integration support site.
support/email❌stringIf a link to the integration support site is not available, you must provide a technical support email.
locationsβœ…arrayThe widget must be displayed in certain interfaces. To use the JavaScript part of the widget, you must fill in an array with the relevant areas.
tour❌objA collection of pictures is available to demonstrate the widget's functionality.
tour/is_tour❌bool indicates whether a tour is included for the widget.
tour/tour_images❌objA set contains localization keys for tour pictures.
tour/tour_images/{lang}❌arrayAn array will contain the path to the images related to the tour, depending on the widget location.
tour/tour_description❌stringAdditionally, a brief text will be displayed when the widget tour is shown. If you set this value to "widget.tour_description", a description that conforms to the localization will be displayed.
settingsβœ…objThe user can access a range of widget settings. These settings fields will appear in the widget settings window and be filled in by the user. This section is only required if "installation" is true. If "installation" is false, then this section is not necessary, because the widget description will be displayed in the settings window. The key in the array is the field code ("FIELD_CODE").
settings/{FIELD_CODE}/name❌stringThe field name will only be a link to the element in the language file.
settings/{FIELD_CODE}/type❌stringField type: Available options are "text", "pass", "users", "users_lp", and "custom".
settings/{FIELD_CODE}/required❌boolIt states whether the field must be filled in by the user
dp❌objBlock Widgets Configuration in the Digital Pipeline. This block must be included in manifest.json only if 'digital_pipeline' is applicable.
dp/settings❌objSimilar to the Settings block, it is displayed when adjusting the widget in the digital pipeline.
dp/settings/action_multiple❌ (but if you add dp, it's required)boolRequired field in the dp block, values (true/false), it determines whether the widget action can be stretched into several stages.
advanced/title❌stringIf the widget provides an advanced settings page in the account Settings section, this field is the page title.
If the value of the field is "advanced.title" then the value is taken from the localization files.
salesbot_designer❌objParameters for adding a widget in the Salesbot constructor
sms/endpoint❌stringIn order for the system to have SMS functionality, the widget must include an sms object and specify an additional sms location. The object should contain a string property endpoint that specifies the address to which the POST request with the required information for sending the SMS will be sent.
mobile/frame_url❌stringIn order to enable mobile application functionality, the widget needs to include a new mobile object and define an additional "mobile_card" location. The mobile object has two properties: "frame_url" and "color". The "frame_url" is the URL that opens in a designated area within the mobile application.
mobile/color❌stringThe color is the HEX code of the color that will be used as a background under the headings of the block with the widget.

Preventing Errors

  • Many files, including manifest.json, are in JSON format. Therefore, it is essential to ensure that the syntax is correct before uploading them. You can use online tools to check the syntax of JSON files. One of the most common mistakes is uploading a file with incorrect syntax.

What’s Next

Next, read about the i18n folder.