Registering a new channel

Kommo API allows developers to integrate various channels for messaging. For the end-user, their work with such channels in the Kommo interface will not differ from the already implemented channels (WhatsApp, Facebook, Telegram, etc.).

In this article, we’ll walk through the basic steps we need to take to start developing an integration with the Chat API.

To begin the development, you’ll need:

• An active Kommo account. You can register for a free trial at https://www.kommo.com.
• A public endpoint on your server where new message notifications will be sent from the Kommo interface.
• A registered chat channel for use in the Chat API.

Requesting a new channel

Within Kommo, the Chat API is responsible for managing chats, channels, and messages.

The Kommo platform itself is responsible for managing leads, contacts, tasks, and other entities, including sources. You can read more about our subject area.

By default, we consider a channel to be a connection of one type of chat (WhatsApp, Viber, Facebook, Online chat to a website, etc.), and it provides the ability to transfer messages between Kommo and the end chat platform through integration.

To register a channel for API chats, you need to send a request to Kommo technical support.

You should submit the request by sending the following checklist using one of the following ways:

• Our social networks ( Live chat, Messenger, Whatsapp, Instagram, Telegram)
• Chat with technical support in chats inside your Kommo account.

The checklist contains the following data:

• The name of the service for which you plan to develop the integration. The name must consist of Latin characters and must not start with a number. The name of the service will be displayed along with the SVG icon in the social profile under the contact name created using this chat channel.
• Webhook URL to which Kommo will send messages. The URL should be of the format https://domain.com/location/:scope_id. The scope_id marker will be dynamically set by the system. You can use it to identify the account from which the message came.
• The list of Kommo accounts IDs allowed to work with the new channel.
• If you want to enable the “write first” feature, you might have to use templates to create a quality experience and reduce spam messages.
• We think the ability to write a message to the user is limited outside a Time Window. So if you need a Time Window, you should provide it in seconds and be willing to display the template selection after the end of the time window.
• Email for communication in case of errors.
• SVG icon of your channel. The icon should be the shape of a circle or fit into it, and its size should be 14x14px.
• Integration ID that will be working with Chat API. First, you should create an integration, and the integration id can be obtained from the keys tab in the integration properties. Read about this in our step-by-step example.
• Integration widget code that will work with Chat API and sources API. The integration you created should contain a widget.
  For marketplace integration, the widget key is set by the integrator and it also can be copied from “My submissions” tab in the settings/integrations page, while for personal integrations, it can be obtained from the keys tab in the integration properties.
• Are you planning to publish your solution to all Kommo users?
  • Is there already a similar solution in Kommo?
  • If there is such a solution, what is unique about yours?

The Kommo technical support team reviews requests within 1-3 business days.

In response, our technical support will provide you with the parameters for accessing the Chat API and the parameters for the registered channel’s bot.

An example of the response

{
	"id": "f62a0162-46a7-430e-b06c-0ef798d56b21",
	"code": "amo.ext.30285908",
	"secret_key": "fb50586ff7b68cd831fe0ef356345903f644c0d2",
	"name": "MyKommo",
	"webhook_url": "https://domain.com/process",
	"enabled": true,
	"test_mode": true,
	"allowed_acc_list": [
		{
			"id": "52fd2a28-d2eb-4bd8-b862-b57934927b38",
			"external_id": "kommo:30285908"
		}
	],
	"contact_email": "integrator@domain.com",
	"created_at": 1669206274,
	"updated_at": 1669206274,
	"write_first": true,
	"webhook_url_v2": "https://domain.com/process",
	"time_window": {
		"enabled": false,
		"expires": 0,
		"tags": null,
		"need_template": false
	},
	"bot": {
		"id": "bb44483d-09dd-4a8e-b5fa-b4b4f67412ea",
		"name": "MyKommo",
		"avatar": "",
		"is_bot": true
	},
	"webhook_events": [
		"messages"
	],
	"icon": "https://st1.kommo.com/origins_icons/amo.ext.30285908.svg?1669206274",
	"webhook_v2": true,
	"time_window_support": false,
	"need_display_template": false,
	"time_window_enum": 0,
	"client_uuid": "b081fb15-3a20-4ef2-afc6-8b517925dbd8"
}

Access Credentials Example

ParameterFrom example

Bot Parameters of the example registered channel

ParameterTypeDescriptionFrom example

Initially, the channel is registered as personal integration, and it will be available only for the accounts specified in the request.

After implementing the integration, it can be published by listing it in our marketplace after passing the moderation so that it becomes possible to connect it to other accounts.

After registering a channel, you can start developing your integration. Let’s start by getting the information about the account id in the chat API.