Connection Areas

Connecting widgets is turning on the functionality of the widget’s JS scripts on certain pages (interfaces) of Kommo. By default, widgets are not connected on all interfaces but only in the requested areas.

Here is a list of all available areas

Our system needs to be told in which areas the widget is going to work and where they are going to use the widgets panel on the extreme right of the card. To do this, in the “locations” block of the manifest.json file, list the required areas, indicating 1 or 0 after the name as a parameter for using the widgets panel (by default, it is 1). Note that the “everywhere” area does not accept this parameter (it is always 0 for this area).

For example, this widget will be initialized on the settings page, in the digital pipeline settings, in the lead sources, in the advanced settings page, and in cards and lists of contacts and leads, but the right column will be used only in the specified cards:

"locations":[
    "lcard-1",
    "llist-0",
    "ccard-1",
    "clist-0",
    "comcard-0",
    "card_sdk",
    "settings",
    "digital_pipeline",
    "lead_sources",
    "catalogs",
    "advanced_settings"
  ]

When connecting the widget in any interface, the JS script will be loaded; the render() callback function will be triggered, followed by init() and bind_actions().

Specifying true or false in the “init_once” block of the manifest.json file controls the ability to call the init() and bind_actions() functions each time the user moves from one area to another or calls them only once. For example, VoIP widgets constantly keep the WebSocket connection and should not be interrupted, so init_once should be set to true. If there is no context common for all pages, it’s better to set it to false.

When initializing the widget in the contact card (ccard) or the lead card (lcard) areas, the widgets panel on the extreme right of the card with your widget appears immediately once the card is opened.

When working with the list areas, the widget won’t be added automatically to the interface. First, the list appears, and once the user selects at least one row from the list using the checkboxes, the context menu appears. Then chooses the widget action from the more button. The widgets panel on the extreme right of the list interface with your widget is added to the page by the selected event, which triggers the corresponding callback function in script.js. Try going to the contacts list, for example, and use the checkboxes to select the desired contacts rows and get the menu with your widget as an option.

Also, for the widget to work in the digital pipeline, you need to specify the digital_pipeline in the locations, the PHP part of the widget with the digital_pipeline endpoint is needed, and the logo_dp.png logo with a resolution of 174×109 is required in the widget.

If your widget has a lead_sources scope, then you can check which pipeline of the account it is bound to using the HTTP request

GET https://myaccount.kommo.com/api/v4/widgets/{widget_code}

The response of such request shows the pipeline_id, or in the script.js of your widget.

To work with the lists SDK, you need to specify a special scope “catalogs“, the id of the list with which the widget will work, and also implement a special callback loadCatalogElement.

Widget page in the Settings section

Kommo widgets can create their own page in the Settings section, and to do this, you need to specify the advanced_settings scope in the “location” list and also add the “advanced” block to the manifest.json, and implement a special callback advancedSettings.

This page is completely controlled by the widget. DOM pages and their structure widgets should form themselves.

The advanced block in the manifest.json should contain the settings page title.

Example of the manifest.json file

{
  "widget":{
    "name": "widget.name",
    "description": "widget.description",
    "short_description": "widget.short_description",
    "version": "1.0.1",
    "interface_version": 2,
    "init_once": false,
    "locale":[
      "en"
    ],
    "installation": true
  },
  "locations":[
    "everywhere",
    "settings",
    "advanced_settings"
  ],
  "settings":{
    "login":{
      "name": "settings.login",
      "type": "text",
      "required": false
    }
  },
  "advanced":{
      "title": "advanced.title"
  }
}

Next, we will see what can we do in the JS part of the widget.