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
Parameter | Required? | Data type | Description |
---|---|---|---|
widget | β | obj | This block contains all the basic settings of the widget. |
widget/name | β | string | 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.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 | β | string | The 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 | β | string | A brief description of the widget's functionality will be displayed on the left side of the modal window. |
widget/version | β | string | The 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 | β | int | The interface version field specifies the system interface widget's loaded version, and it should be set to 2. |
widget/init_once | β | bool | The 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 | β | array | To 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 | β | bool | The "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 | β | obj | A set of the widget support information. |
support/link | β | string | You must provide a valid and functional link to the integration support site. |
support/email | β | string | If a link to the integration support site is not available, you must provide a technical support email. |
locations | β | array | The 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 | β | obj | A 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 | β | obj | A set contains localization keys for tour pictures. |
tour/tour_images/{lang} | β | array | An array will contain the path to the images related to the tour, depending on the widget location. |
tour/tour_description | β | string | Additionally, 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 | β | obj | The 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 | β | string | The field name will only be a link to the element in the language file. |
settings/{FIELD_CODE}/type | β | string | Field type: Available options are "text" , "pass" , "users" , "users_lp" , and "custom" . |
settings/{FIELD_CODE}/required | β | bool | It states whether the field must be filled in by the user |
dp | β | obj | Block Widgets Configuration in the Digital Pipeline. This block must be included in manifest.json only if 'digital_pipeline' is applicable. |
dp/settings | β | obj | Similar 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) | bool | Required field in the dp block, values (true/false), it determines whether the widget action can be stretched into several stages. |
advanced/title | β | string | 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 | β | obj | Parameters for adding a widget in the Salesbot constructor |
sms/endpoint | β | string | In 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 | β | string | In 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 | β | string | 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. |
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.
Updated 5 months ago