Step 1: Register a new channel

Kommo provides developers with the ability to integrate various messaging channels. For users, the experience of interacting with these channels through the Kommo interface will be seamless, similar to existing channels such as WhatsApp, Facebook, and Telegram.

❗️

Please, be aware that you need to create a chat channel and continue with Chats API if only you develop your own integration with a messenger.

This article will guide you through the basic steps required to begin developing an integration with the Chat API.

To get started with development, you'll need:

  • An active Kommo account. You can sign up for a free trial.
  • A public endpoint on your server where new message notifications will be received from the Kommo interface.
  • A registered chat channel to be used with the Chat API.

Request a new channel

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

By default, a channel in Kommo refers to a specific type of chat platform such as WhatsApp, Viber, Facebook, or an online chat on a website. It facilitates the exchange of messages between Kommo and the respective chat platform through integration.

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

You request should contain:

List itemMandatory?Description
1. Name of the serviceThe name of the service for which you plan to develop the integration. This name will be displayed alongside the SVG icon on the social profile under the contact name created using this chat channel. Please ensure that the name of the service contains only Latin characters and does not start with a number.
2. Webhook URLWebhook URL where Kommo will send messages should be in the format https://domain.com/location/:scope_id. The scope_id marker will be dynamically set by the system and can be used to identify the account from which the message came.
3. Kommo account IDA Kommo account ID that will work with the new channel.
4. Write First featureIn order to use the Write first feature, you may need to utilize templates to ensure a high-quality experience and minimize spam messages.
5. Time WindowDue to the fact that many integrations limit the ability to send messages after a certain period, we have added support for Time Windows. The integration itself determines the length of the Time Window. In the profile, after each incoming message, the timer will reset and count down the time until the end of the Time Window. An integration can also indicate that it needs to block the message sending control after the Time Window expires. Once the message sending control is blocked, the user will still have the option to select a template for sending.
So if you need a Time Window:
5.1 you should provide duration of the Window in seconds and 5.2 you should choose if chat template are displayed after Time Window expiration.
6. EmailEmail for communication in case of any problems.
7. SVG iconSVG icon of your channel. The icon should be round or fit into it, and its size should be 14x14px.
8. Integration ID ID of an integration 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.
9. Integration widget codeIntegration widget code that will work with Chat API and sources API. The integration you created should contain a widget.
For public 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 private integrations, it can be obtained from the keys tab in the integration properties.
10. Private/publicAre 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?
11. Advanced Does the integration store files?This is necessary to determine whether the integration stores files on its side that are sent to the Kommo chat API. This setting affects the behavior of the delayed upload functionality. The file must be accessible via the link sent in the webhook.
12. Advanced Does the integration support reactions?If the integration supports certain reactions, please provide them in the format: 👍😳.
13. Advanced Does the integration support quoting messages?The message quoting feature in a messenger allows users to reference specific messages in a conversation.
14. Advanced Does the integration support voice messages?The voice message support feature in a messenger allows users to send and receive audio messages instead of text.
15. Advanced What is the maxixmum file size available to send in the chat?If your chat supports file sharing, please provide information on the maximum file size allowed for this chat channel.

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.

❗️

We DO NOT recommend to connect more than one chat channel to an integration. If you connect more than one, you can experience unexpected implications.

An example of the response

{
    "result": {
        "en": {
            "id": "dw2asda2-929f-47c3-b1e7-c845a941833b",
            "code": "Codechat",
            "secret_key": "1eqadw323ead22wW2E1SA",
            "name": "Chat",
            "webhook_url": "https://webhook.site/4e6a83e5-90d02-4212192c-9c6d-adwdas212",
            "enabled": true,
            "test_mode": true,
            "allowed_acc_list": [
                {
                    "id": "1232d-d75c-4ee0-2dasd3-21easda212",
                    "external_id": "amocrm:1234567"
                }
            ],
            "contact_email": "[email protected]",
            "created_at": 1732273375,
            "updated_at": 1732273375,
            "widget_code": "sadedf234fdq2easd2312sdws",
            "supports_reply": true,
            "write_first": true,
            "webhook_url_v2": "https://webhook.site/4e6a83e5-90d02-4212192c-9c6d-adwdas212",
            "time_window": {
                "enabled": true,
                "expires": 100000,
                "tags": null,
                "need_template": true
            },
            "bot": {
                "id": "adads312-7ad01b-asdw3d23-das213-243r513sa",
                "name": "Chat",
                "is_bot": true
            },
            "webhook_events": [
                "messages",
                "typing"
            ],
            "saves_files": true,
            "supports_voice": true,
            "supports_delivery_notification": true,
            "icon": "https://st1.amocrm.com/origins_icons/Chat.svg?1732273375",
            "webhook_v2": true,
            "time_window_support": true,
            "need_display_template": true,
            "time_window_enum": 100000,
            "reactions_all": true,
            "reactions_list": "",
            "picture_size": 2,
            "video_size": 2,
            "voice_size": 2,
            "file_size": 2,
            "opposite_platform_enabled": false,
            "client_uuid": "adwdasd2-21e2sdd-40ee-2dasd21-21e21e2esa"
        }
    },
    "error": null
}

Example of access credentials for online chats

ParameterExample
Channel codeamo.ext.12345678
Channel ID1234567-12be-4sr6-qwe3-0r12345446t201
Channel secret12345678supersecret1234567
An account connected to the channel12345678

Bot Parameters of the example registered channel

ParameterData typeDescriptionExample
idstringChat participant ID on the Kommo side (amojo_id)55c5555a-5ad5-4555-a555-555d55b5e5b5
client_idstringChat participant ID on the integration side987654321-48d75-r4c89nt7-9ct4c
namestringBot nameMyKommo

After implementing the integration, it can be published in our Marketplace once it has passed moderation. This will allow it to be connected to other accounts.

If the channel is connected to a private integration, it will only be accessible to the account specified in the request.