Widgets

In this section we will describe API methods for working with widgets.

Table of Contents

Widgets List

Method

GET /api/v4/widgets

Description

This method returns an aggregated list of public widgets installed on the account as well as widgets added by the current user.

Limitations

Methos is available for all account users.

GET parameters

Parameter Data type Description
page int Sample page
limit int The number of entities returned in the response of one request (limit – 250)

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized

Response parameters

Method returns a collection of widget models. The properties of the model are listed below.

Parameter Data type Description
id int Widget ID
code string Widget code
version string Widget version
rating string|float Widget rating
settings_template array An array of widget settings fields
settings_template[0] object Widget settings field
settings_template[0][key] string Field value key
settings_template[0][name] string Widget settings field name
settings_template[0][type] string Widget settings field data type (text, pass, custom, users, or users_lp)
settings_template[0][is_required] bool Defines whether a setting is mandatory
is_lead_source bool Defines whether a widget can be set as a lead source
is_work_with_dp bool Defines whether a widget is available in Digital Pipeline
is_crm_template bool Defines whether a widget is a CRM template
client_uuid string|null UUID of the widget’s oAuth integration
is_active_in_account bool Defines whether the widget is installed in the account
pipeline_id int Pipeline ID where a widget is set as a lead source

Response example


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/widgets?limit=2&page=1"
        },
        "next": {
            "href": "https://example.kommo.com/api/v4/widgets?limit=2&page=2"
        }
    },
    "_embedded": {
        "widgets": [
            {
                "id": 742,
                "code": "amo_dropbox",
                "version": "0.0.13",
                "rating": "2,8",
                "settings_template": [
                    {
                        "key": "conf",
                        "name": "custom",
                        "type": "custom",
                        "is_required": false
                    }
                ],
                "is_lead_source": false,
                "is_work_with_dp": false,
                "is_crm_template": false,
                "client_uuid": null,
                "is_active_in_account": false,
                "pipeline_id": null,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/widgets/amo_dropbox"
                    }
                }
            },
            {
                "id": 796,
                "code": "amo_mailchimp",
                "version": "1.1.12",
                "rating": "3,4",
                "settings_template": [
                    {
                        "key": "api",
                        "name": "custom",
                        "type": "custom",
                        "is_required": false
                    }
                ],
                "is_lead_source": false,
                "is_work_with_dp": false,
                "is_crm_template": false,
                "client_uuid": null,
                "is_active_in_account": false,
                "pipeline_id": null,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/widgets/amo_mailchimp"
                    }
                }
            }
        ]
    }
}

Getting the widget info by its code

Method

GET /api/v4/widgets/{widget_code}

Description

This method allows to get the information on a public widget or a private widget uploaded by the current user.

Limitations

Method is available for all account users

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
404 Widget isn’t found or is unavailable
401 User is not authorized

Response parameters

Method returns a widget model. The properties of the model are listed below.

Parameter Data type Description
id int Widget ID
code string Widget code
version string Widget version
rating string|float Widget rating
settings_template array An array of widget settings fields
settings_template[0] object Widget settings field
settings_template[0][key] string Field value key
settings_template[0][name] string Widget settings field name
settings_template[0][type] string Widget settings field data type (text, pass, custom, users, or users_lp)
settings_template[0][is_required] bool Defines whether a setting is mandatory
is_lead_source bool Defines whether a widget can be set as a lead source
is_work_with_dp bool Defines whether a widget is available in Digital Pipeline
is_crm_template bool Defines whether a widget is a CRM template
client_uuid string|null UUID of the widget’s oAuth integration
is_active_in_account bool Defines whether the widget is installed in the account
pipeline_id int Pipeline ID where a widget is set as a lead source
settings array Widget settings. The key is returned only when an integration requests its own settings

Response example


{
    "id": 742,
    "code": "amo_dropbox",
    "version": "0.0.13",
    "rating": "2,8",
    "settings_template": [
        {
            "key": "conf",
            "name": "custom",
            "type": "custom",
            "is_required": false
        }
    ],
    "is_lead_source": false,
    "is_work_with_dp": false,
    "is_crm_template": false,
    "client_uuid": null,
    "is_active_in_account": false,
    "pipeline_id": null,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/widgets/amo_dropbox"
        }
    }
}

Installing the widget into the account

Method

POST /api/v4/widgets/{widget_code}

Description

This method allows installing the widget into the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To install a widget, mandatory parameters based on the widget settings should be passed. Available field types and their format are listed below

Parameter Data type Description
text string Value for this type is passed as a regular string
pass string Value for this type is passed as a regular string
users object An object containing user ID as key and his extension number as value
users_lp object An object containing user ID as key and an object with login and password as value
users_lp[{user_id}][login] object User login
users_lp[{user_id}][password] object User password

An example of the request

In the following example we’ll pass fields required to install the amo_asterisk widget.
Fields “login” and “script_path” have the “text” type.
Field “password” has the “pass” type.
Field “phones” has the “users” type.


{
    "login": "example",
    "password": "eXaMp1E",
    "phones": {
        504141: "1039"    
    },
    "script_path": "https://example.com/"
}

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Widget has been installed successfully
404 Widget was not found
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns an object of the installed widget and its settings. The properties of the model are similar to properties returned in the widget getting method.

Response example


{
    "id": 972,
    "code": "amo_asterisk",
    "version": "1.1.6",
    "rating": "2,7",
    "settings_template": [
        {
            "key": "login",
            "name": "Login",
            "type": "text",
            "is_required": true
        },
        {
            "key": "password",
            "name": "Password",
            "type": "pass",
            "is_required": true
        },
        {
            "key": "phones",
            "name": "Phone numbers",
            "type": "users",
            "is_required": true
        },
        {
            "key": "script_path",
            "name": "Script path",
            "type": "text",
            "is_required": true
        }
    ],
    "is_lead_source": false,
    "is_work_with_dp": false,
    "is_crm_template": false,
    "client_uuid": null,
    "is_active_in_account": true,
    "pipeline_id": null,
    "settings": {
        "login": "example",
        "password": "eXaMp1E",
        "phones": {
            "504141": "1039"
        },
        "script_path": "https://example.com/"
    },
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/widgets/amo_asterisk"
        }
    }
}

Uninstalling widget

Method

DELETE /api/v4/widgets/{widget_code}

Description

This method allows to uninstalli a widget by its code.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

HTTP response codes.

Response code Case
204 Widget has been uninstalled successfully
404 Widget was not found
403 Insufficient rights to call this method
401 User is not authorized

Response parameters

Method does not return a body

SalesBot widget block execution confirmation

Method

POST /api/v4/{salesbot|marketingbot}/{bot_id}/continue/{continue_id}

Description

Method receives data after successful execution of the widget block in SalesBot and continues the Bot workflow.
You can read more about the Salesbot method widget_request here.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

If the widget needs to pass any data, it should be put into the “data” field as an array

Parameter Data type Description
data array Data for widget, can be acquired in the SalesBot code with the key {{json.ARRAY_KEY_NAME}}, where ARRAY_KEY_NAME is the name of the field passed into “data”

An example of the request

In the following example, we’ll pass a “status” field to the widget. The widget will be able to get the field’s value (“success”) in any block after the widget_request by the {{json.status}} key.


{
    "data": {
        "status": "success"    
    }
}

HTTP response codes.

Response code Case
202 Widget has been successfully launched
404 Record of the widget awaiting the execution result was not found
401 User is not authorized

Response parameters

Method does not return a body