Sources API

This functionality allows you to choose the origins of where the incoming leads come from. These origins are called Sources.

Contents

  1. Sources API
  2. Get a list of sources
  3. Add sources
  4. Update sources
  5. Update one source
  6. Delete sources
  7. Delete one source

Through the sources API methods, the integration can only manage its own sources, and it’s identified by verifying the passed Access Token used when creating each source.

Each source has a unique code (external_id), and there can not be two sources with the same code.

One integration can create up to 50 sources.

The sources API allows the integration to create incoming leads and determine in which pipeline it will create them.

After creating sources using the integration, they will appear

  • In the source field of the incoming lead created via the chat API.
  • In the channels field for the Message option when setting up a bot.
  • In the list of contact options, when clicking on the phone number of a contact/company, if the Write First functionality is activated
  • In the Statistics tab of the lead card created using one of the sources, the source name will appear.

You also can specify the source when creating a lead via API using the complex method by sending the object _embedded[source] with the source id in the source external_id and source type always set to “widget”.

"source":
        {
           "external_id": "ufi7pscriq7foaaz2afxakxtuf2yytuh7vjg1pxr",
           "type": "widget"
        }

Integration requirements for working with the sources API

The sources generated by the integration are displayed in the corresponding Digital Pipeline settings section.

The user can interact with the source and integration through the interface.

Before you start working with the sources API, you need to make sure that the integration meets the following criteria:

  1. The integration has a widget, and its manifest.json file specifies the ability to display the widget in the interface for adding a new source “locations”:[“lead_sources”]
  2. For integrations that work with chats: the widget code and integration ID must be specified in the chat channel when registering it.

When creating a new integration, you can choose to enable the Multiple sources function. This flag should be enabled when the integration fully manages the sources through the API from its backend and creating the source from the Kommo side is no longer required. If the flag is not set, the source will be created on the Kommo side when the integration is installed.

Get a list of sources

Method

GET /api/v4/sources

Description

The method allows you to get a list of the integration sources.

Restrictions

The method is available with administrator rights. Returns up to 50 sources.

Request header

Content-Type: application/json

GET parameters

Parameter Data type Description
filter[external_id] string|array Filter by external source ID

Data type header on success

Content-Type: application/hal+json

Data type header on error

Content-Type: application/problem+json

HTTP response codes

Code Condition
200 Leads have been successfully created
204 The integration does not have any sources or the search filter did not return any results
401 Integration not authorized

Response example

{
   "_total_items": 2,
   "_links": {
       "self": {
           "href": "https://subdomain.kommo.com/api/v4/sources"
       }
   },
   "_embedded": {
       "sources": [
           {
               "id": 17619939,
               "name": "chat",
               "pipeline_id": 5867030,
               "external_id": "kchat01",
               "services": [],
               "default": false,
               "origin_code": "kommo.ext.30470678",
               "_links": {
                   "self": {
                       "href": "https://subdomain.kommo.com/api/v4/sources/17619939"
                   }
               }
           },
           {
               "id": 17619943,
               "name": "test_chat",
               "pipeline_id": 5884544,
               "external_id": "kchat02",
               "services": [],
               "default": false,
               "origin_code": "kommo.ext.30470678",
               "_links": {
                   "self": {
                       "href": "https://subdomain.kommo.com/api/v4/sources/17619943"
                   }
               }
           }
       ]
   }
}

Response parameters

Parameter Data type Description
id int Source id
name string Source name
pipeline_id int Pipeline id. The pipeline might be archived.
external_id string External ID of the source on the integration side
default bool A boolean indicates whether this source is the default source. It might be null.
services array An array of services that are associated with the source. The data from this array is used to display in the website chat button (buttons on the site).
services[type] string service type. It might be empty.
services[pages] string Contains a list of elements that can be selected when setting up the website chat button (buttons to the site)
services[0][pages][0][name] string The name of the item displayed to the user in the drop-down list when setting up a button on the site
services[0][pages][0][id] string Identifier of the item in the dropdown list (not displayed to the client and user)
services[0][pages][0][link] string The id of the user that will be indicated in the messenger button and to which the client will write on the site page. For example, for Whatsapp, the link will be generated as follows: https://wa.me/{Specified phone number}
origin_code string
null		 Main channel code of the source. This chat channel will be used when initializing the chat. The field is optional, but when specified, it shouldn’t be null, just numbers, have double quotations, or have more than 20 characters.

Add sources

Method

POST  /api/v4/sources

Description

The method allows you to post a list of the integration sources.

Restrictions

The method is available with administrator rights. Post no more than 50 sources.

Request header

Content-Type: application/json

Body example

[
   {
       "name": "chat",
       "external_id": "Kchat01",
       "origin_code": "kommo.ext.30470678",
       "pipeline_id": 5867030
   },
    {
       "name": "test_chat",
       "external_id": "Kchat02",
       "origin_code": "kommo.ext.30470678",
       "pipeline_id": 5884544
    }
]

Body parameters

Parameter Data type Description
name string Source name
pipeline_id int Pipeline id. The pipeline might be archived. The field is optional. If not provided, the source will be added to the main pipeline.
external_id string External ID of the source on the integration side
default bool A boolean indicates whether this source is the default source. The field is optional.
origin_code string Code of the main chat channel of the source. This chat channel will be used when initializing the chat. The field is optional, but when specified, it shouldn’t be null, just numbers, double quotations, or more than 20 characters.
services array An array of services that are associated with the source. The data from this array is used to display in the website chat button (buttons on the site).
services[type] string service type. It might be empty.
services[pages] string Contains a list of elements that can be selected when setting up the website chat button (buttons to the site)
services[0][pages][0][name] string The name of the item displayed to the user in the drop-down list when setting up a button on the site
services[0][pages][0][id] string Identifier of the item in the dropdown list (not displayed to the client and user)
services[0][pages][0][link] string The id of the user that will be indicated in the messenger button and to which the client will write on the site page. For example, for Whatsapp, the link will be generated as follows: https://wa.me/{Specified phone number}

Data type header on success

Content-Type: application/hal+json

Data type header on error

Content-Type: application/problem+json

Response example

{
    "_total_items": 2,
    "_embedded": {
        "sources": [
            {
                "id": 17619939,
                "name": "chat",
                "pipeline_id": 5867030,
                "external_id": "kchat01",
                "services": [],
                "default": false,
                "origin_code": "kommo.ext.30470678",
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://subdomain.kommo.com/api/v4/sources/17619939"
                    }
                }
            },
            {
                "id": 17619943,
                "name": "test_chat",
                "pipeline_id": 5884544,
                "external_id": "kchat04",
                "services": [],
                "default": false,
                "origin_code": "kommo.ext.30470678",
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://subdomain.kommo.com/api/v4/sources/17619943"
                    }
                }
            }
        ]
    }
}

HTTP response codes

Code Condition
200 Sources have been successfully created
204 The integration does not have any sources or the address is not right
400 Bad request: might be because a source with the same external id already exists or the pipeline id does not exist
401 The integration is not authorized

Update sources

Method

PATCH  /api/v4/sources

Description

The method allows you to edit sources in batches. An array of source objects is passed.

Restrictions

The method is available with administrator rights. You can update up to 50 sources at the same time

Request header

Content-Type: application/json

Body example

[
   {
       "id": 17619939,
       "default": true
   },
   {
       "id": 19352935,
       "name": "call"
   }
]

Body parameters

Parameter Data type Description
id int Id of the source you want to edit. Required field.
name string Source name
pipeline_id int Pipeline id. The pipeline might be archived. The field is optional. If not provided, the source will be added to the main pipeline.
default bool A boolean indicates whether this source is the default source. The field is optional.
origin_code string Code of the main chat channel of the source. This chat channel will be used when initializing the chat. The field is optional, but when specified, it shouldn’t be null, just numbers, double quotations, or more than 20 characters.
services array An array of services that are associated with the source. The data from this array is used to display in the website chat button (buttons on the site).
services[type] string service type. It might be empty.
services[pages] string Contains a list of elements that can be selected when setting up the website chat button (buttons to the site)
services[0][pages][0][name] string The name of the item displayed to the user in the drop-down list when setting up a button on the site
services[0][pages][0][id] string Identifier of the item in the dropdown list (not displayed to the client and user)
services[0][pages][0][link] string The id of the user that will be indicated in the messenger button and to which the client will write on the site page. For example, for Whatsapp, the link will be generated as follows: https://wa.me/{Specified phone number}

Response example

{
    "_total_items": 2,
    "_embedded": {
        "sources": [
            {
                "id": 17619939,
                "name": "chat",
                "pipeline_id": 5867030,
                "external_id": "kchat01",
                "services": [],
                "default": true,
                "origin_code": "kommo.ext.30470678",
                "_links": {
                    "self": {
                        "href": "https://subdomain.kommo.com/api/v4/sources/17619939"
                    }
                }
            },
            {
                "id": 19352935,
                "name": "call",
                "pipeline_id": 5884544,
                "external_id": "gp02",
                "services": [],
                "default": false,
                "origin_code": null,
                "_links": {
                    "self": {
                        "href": "https://subdomain.kommo.com/api/v4/sources/19352935"
                    }
                }
            }
        ]
    }
}

Data type header on success

Content-Type: application/hal+json

Data type header on error

Content-Type: application/problem+json

HTTP response codes

Code Condition
200 Sources have been successfully updated
400 Incorrect data transmitted. Details are available in the response body
401 The integration is not authorized

Update one source

Method

PATCH  /api/v4/sources/{id}

Description

The method allows you to edit a specific source.

Restrictions

The method is available with administrator rights. Post no more than 50 sources.

Request header

Content-Type: application/json

Header parameter

Parameter Data type Description
id int Id of the source you want to edit

Body example

{
    "default": true
}

Body parameters

Parameter Data type Description
name string Source name
pipeline_id int Pipeline id. The pipeline might be archived. The field is optional. If not provided, the source will be added to the main pipeline.
default bool A boolean indicates whether this source is the default source. The field is optional.
origin_code string Code of the main chat channel of the source. This chat channel will be used when initializing the chat. The field is optional, but when specified, it shouldn’t be null, just numbers, double quotations, or more than 20 characters.
services array An array of services that are associated with the source. The data from this array is used to display in the website chat button (buttons on the site).
services[type] string service type. It might be empty.
services[pages] string Contains a list of elements that can be selected when setting up the website chat button (buttons to the site)
services[0][pages][0][name] string The name of the item displayed to the user in the drop-down list when setting up a button on the site
services[0][pages][0][id] string Identifier of the item in the dropdown list (not displayed to the client and user)
services[0][pages][0][link] string The id of the user that will be indicated in the messenger button and to which the client will write on the site page. For example, for Whatsapp, the link will be generated as follows: https://wa.me/{Specified phone number}

Response example

{
    "id": 17619939,
    "name": "chat",
    "pipeline_id": 5867030,
    "external_id": "kchat01",
    "services": [],
    "default": true,
    "origin_code": "kommo.ext.30470678",
    "_links": {
        "self": {
            "href": "https://subdomain.kommo.com/api/v4/sources/17619939"
        }
    }
}

Data type header on success

Content-Type: application/hal+json

Data type header on error

Content-Type: application/problem+json

HTTP response codes

Code Condition
200 Sources have been successfully updated
400 Incorrect data transmitted. Details are available in the response body
401 The integration is not authorized
404 The source id isn’t found

Delete sources

DELETE  /api/v4/sources

Description

The method allows you to delete the integration sources in batches. An array of source objects is passed.

Restrictions

The method is available with administrator rights.

Request header

Content-Type: application/json

Body example

[
   {
       "id": 17489247
   },
   {
       "id": 17489251
   }
]

Body parameters

Parameter Data type Description
id int The external id of the source you want to delete.

HTTP response codes

Code Condition
204 Sources have been successfully deleted, but there is nothing to return.
400 Bad request: a source with the external id doesn’t exist
401 The integration is not authorized

Delete one source

DELETE  /api/v4/sources/{id}

Description

The method allows you to remove a specific source.

No request body is not required to be passed.

Restrictions

The method is available with administrator rights.

Request header

Content-Type: application/json

Header parameter

Parameter Data type Description
id int The external id of the source you want to delete.

HTTP response codes

Code Condition
204 Source has been successfully deleted, but there is nothing to return.
401 The integration is not authorized
404 Bad request: a source with the external id doesn’t  exist