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 item | Mandatory? | Description |
---|---|---|
1. Name of the service | ✅ | The 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 URL | ✅ | Webhook 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 ID | ✅ | A Kommo account ID that will work with the new channel. |
4. Write First feature | ❌ | In 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 Window | ✅ | Due 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. Email | ✅ | Email for communication in case of any problems. |
7. SVG icon | ✅ | SVG 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 code | ✅ | Integration 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/public | ✅ | 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? |
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
Parameter | Example |
---|---|
Channel code | amo.ext.12345678 |
Channel ID | 1234567-12be-4sr6-qwe3-0r12345446t201 |
Channel secret | 12345678supersecret1234567 |
An account connected to the channel | 12345678 |
Bot Parameters of the example registered channel
Parameter | Data type | Description | Example |
---|---|---|---|
id | string | Chat participant ID on the Kommo side (amojo_id) | 55c5555a-5ad5-4555-a555-555d55b5e5b5 |
client_id | string | Chat participant ID on the integration side | 987654321-48d75-r4c89nt7-9ct4c |
name | string | Bot name | MyKommo |
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.