manifest.json

The only required file when creating the widget. It’s a JSON-formatted file that provides metadata associated with the widget. This metadata 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": "support@kommo.com"
    }
  },
  "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" 
   }
}

Note

Any value of the form (widget.name, widget.description, advanced.title), means that it will be taken from the corresponding i18n folder file, depending on the localization. They are needed if your widget should work in more than one language.

Properties of the file manifest.json

The properties of this file are in this table

Settings Description
widget This block contains all the basic settings of the widget
widget/name
required 		The 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. See an example.
Note: If the widget is uploaded to a Marketplace integration, the name specified in the integration will be used, but the field is still mandatory.
widget/description
required 		The full description of the widget is shown in the widget settings window. It should contain the path to the translation in the language files. You can use HTML tags, as well as special short tags, in order to form the most personalized description, like if you need to provide a description showing to the user the subdomain of the Kommo account in which they work.
List of tags:
#HOST# is the current host;
#SUBDOMAIN# is account subdomain;
#LOGIN# is the login of the current user, authorized user;
#ACCOUNT_ID# is the id of the current account in the system;
#USER_ID# is the id of the current user on the system;
#TOP_LEVEL_DOMAIN# is the top-level domain (com).
Note: If the widget is uploaded to the a Marketplace integration, the description specified in the integration will be used, but the field is still mandatory.
widget/short_description
required 		A brief description of the widget functionality will be located on the left side of the modal window.
widget/version Widget version. It only carries an informative load. (It is recommended to increase the version every time you upload the widget archive in order to have up-to-date files in the system)
widget/interface_version
required 		(int) The interface version (1,2) for which system interface the widget is loaded. You must use 2.
widget/init_once (true/false) indicates whether it’s necessary to compile the js object widget one time per session with the Kommo interface. When the widget is initialized, the render(), init() and bind_actions() functions are called (more about them in the part script.js).
Specifying true or false controls the ability to call the init() and bind_actions() functions each time when changing from an area to an area (for more information about connection areas), or to call them only once.
For example, VoIP widgets keep the WebSocket connection constantly and it should not be interrupted, so widget/init_once should be set to true. If there is no common context for all pages, then it’s better to put the value to false.
widget/locale
required 		An array of language codes in which the widget will be available. Each language should have its own translation file in the i18n folder. Available languages: en, es, pt (English, Spanish, and Portuguese respectively).
Note: When publishing a widget in Kommo Marketplace, the language files must match the languages that are filled in the integration and support must be provided in the available languages.
widget/installation
required 		(true/false) If set to true, settings will appear during the installation. If set to false, then the widget will only appear in the widget list, without asking for settings or installations in the account. This happens when all the settings occur in another system that interacts with Kommo via the API.
widget/support A set of the widget support information.
support/link Link to the integration support site. You should provide a valid link.
support/email Technical support email. It will be used if there is no link for integration support site.
locations
required 		The interfaces in which the widget should be displayed. An array that must be filled in if you want to use the js part of the widget. More about the areas.
tour A set of pictures that demonstrate the functionality of a widget.You can find out more in the JS-Widget. See the example.
tour/is_tour (true/false) indicates whether a tour is included for the widget.
tour/tour_images A set contains localization keys for tour pictures.
tour/tour_images/{lang} An array contains the path to the images for the tour depending on the location
tour/tour_description A short text that will be displayed when the widget tour is displayed. If set to the value widget.tour_description, a description according to the localization will be shown.
settings
required 		A set of the widget settings available to the user. The settings fields will appear in the widget settings window and filled in by the user. See the example.
This section is required only if installation is true. If installation is false, then this section is not needed, because in the settings window, only the description of the widget will be displayed. The key in the array is the field code {FIELD_CODE}
settings/{FIELD_CODE}/name Field name (only a link to the element in the lang file)
settings/{FIELD_CODE}/type Field type. Available options: text, pass, users, users_lp, custom.
Read more about Fields Types .
settings/{FIELD_CODE}/required (true/false) whether the field must be filled in by the user.
dp Block widgets configuration in the digital pipeline. This block must be included in manifest.json only if there is a scope of digital_pipeline. With the digital pipeline functionality, only public widgets that have a file widget.php can work, in which there is an endpoint digital_pipeline (more details Digital pipeline)
dp/settings Similar to the settings block, but it will be displayed when adjusting the widget in the digital pipeline.
dp/settings/action_multiple Required field in the dp block, values (true/false), determines whether the widget action can be stretched into several stages
advanced/title If 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 Parameters for adding a widget in the Salesbot constructor. Read more about salesbot .
sms/endpoint To support the system SMS functionality, the widget must contain an sms object and specify an additional sms location. The object has a string property endpoint represents the address to which the POST request will be sent with the information needed to send the SMS.
mobile/frame_url To support the functionality of working with in a mobile application, the widget must contain a new mobile object and specify an additional mobile_card location. The object has two properties frame_url and color.
The frame_url is the address that will be opened in a special area in the mobile application.
mobile/color The color is the HEX code of the color that will be used as a background under the headings of the block with the widget.

Next, Localizations