Chat capabilities
Kommo is known as a messenger-based CRM, and its strength comes from the excellent integration with different chat channels.
The essence of integrating chats with Kommo is that the Kommo user has the ability to exchange messages with their clients from different channels in Kommo and respond to them from the system interface, while the clients use the messenger they are used to for communication.
When receiving a message from a new chat channel, Kommo will create a chat, a contact, and an incoming lead.
A chat is associated with a contact. Every contact can have several chats from different channels, as well as from various sources of the same channel.
Information about the connection (contact/company) is stored, like name, phone, email, and the user’s avatar (if provided).
If the connection has a lead or customer, chats aren’t displayed on the connection’s card but in the leads or customers.
When a message comes to the Kommo account, account managers receive notifications in the notification center, represented by the bell icon located in the lower-left corner of the screen in the web version.
Notifications also come to the phone if the mobile application is installed. That’s why you should consider not overusing the notifications so that the user is not forced to turn them off in his profile.
Message exchange
The diagram below shows the process of sending and receiving messages via the Kommo account.
Next, we will cover the main features of the Chat API from the user’s viewpoint, as well as additional ones that can make your integration more beneficial for the user.
Key Features of the Chat API
Receiving messages from external channels in Kommo
One of the main functions of the Chats API is the ability to receive messages from external channels in Kommo.
The integration acts as a transport for messages from a third-party chat system to Kommo.
When a message enters a new chat, Kommo will create an incoming lead message in the pipeline.
In this example, Telegram integration works as a shipper between Telegram application and Kommo. The client sends from Telegram.
Sending messages from the Kommo interface
The next main feature of the Chat API is the ability to send messages from Kommo to an external channel. Messages can be sent from a card or a bot.
The message may contain the following information:
- Message text
- Media files added to the message
- Buttons
- Information about the selected template and replaced placeholders if a template is sent.
In this example, The Kommo user sends messages from the Kommo interface, while the message comes to Kommo from Telegram.
Update the status of a sent message
The Chat API also supports the status of sent messages.
The integration can keep the up-to-date status and update it via the API for each sent message.
| Status | When status should be used | Enum status value |
|---|---|---|
| Sent | The message was sent from Kommo | – |
| Delivered | The message was delivered to destination | 1 |
| Read | Message was read by recipient | 2 |
| Error | Message was not delivered | -1 |
Message is sent
Message is delivered
Message was read
An error happened
Send message error output
In addition to the sending status of the sent message, the integration can send information about the error.
There are several predefined error types, as well as a custom type.
| Error Code | When should the code be sent? |
|---|---|
| 901 | The user has deleted the message |
| 902 | Integration disabled on channel side |
| 903 | Internal server error |
| 904 | Unable to create a conversation (For example, the user is not registered in WhatsApp) |
| 905 | Any other, along with this error code, you must send the error text |
The error message appears as in the following picture, and when you hover the “Error” mark, you can see the error message.
Import chat history and channel bot
In addition to the implementation of existing chat, the Chat API can import old messages.
Old messages can be imported, whether the client or the manager sent them.
Outgoing messages sent in a third-party application are difficult to associate with a specific Kommo user; therefore, we provide an integration bot on behalf of which you can import such messages.
Messages from the bot are displayed on the corresponding card with the channel’s name and the bot’s avatar pre-installed in the system.
If you have already registered a channel, you can find the bot information (id, name, avatar) in the message received from the technical support when registering the chat channel in the “bot” part.
Note:When importing, you should also consider that the history display is limited to days before the lead creation date.
Additional features that can be implemented by integration
Creating a chat and linking it to an existing contact
For more complex cases, when the history of the chat is needed “here and now”, The Chat API has special methods to allow the user to create a chat and link it to any connection ( contact, company) in the user’s account.
Getting the history of a chat
The Chat API provides a method for getting the chat history within the specified chat. The integration can only access the chats that it has created.
Functionality “Write first”
Generally, the conversation can only be initiated by the client, but some messengers support the ability to initiate communication with the client. To do this, Chat API provides the “Write first” functionality. The identifier for this functionality is a phone number.
The Kommo user can initiate the communication in the lead card by clicking on the phone number and selecting the source. There is also such an opportunity in Salesbot.
To use this feature, just create a lead card and add a contact with a phone number.
Channels that support the feature will be displayed in the Click-To-Call drop-down list.
The user selects “Your widget” and sends a message through the standard message writing interface.
After writing the message, Kommo will send a Webhook, in which the chat identifiers, the recipient, and the message from the Kommo side are transmitted.
The integration server should process the request and try to send the message to the recipient. After successfully sending a message or inability to send it, the integration should send a request to Kommo to change the status of the message.
Ability to connect multiple sources for one channel
Kommo provides the possibility to chat from various sources, which can be helpful in replicated integrations that need to support multiple messenger sources through one integration channel, such as numerous WhatsApp numbers.
For the integration to support multiple sources, it must create the corresponding entities through the sources API and transmit data about the source with each message.
One integration can have up to 50 sources in one Kommo account.
You can add many sources for the same integration, and attach the leads from each source to different pipeline.
The next pictures show that we have two Kommo users: one is a sales representative and the other from the support team, and each with their own whatsapp number. Messages for each manager were sent to the corresponding pipeline.
The customer speaks with the sales for their business questions
and with support for help in technical matters
Kommo users can send messages from their account interface each using thier corresponding channel.
Typing status display
In addition to sending printed messages to Kommo, we can notify the integration if the user is typing now.
You can receive “typing” event hooks to broadcast them to the integrated messenger.
Time window support
Since many integrations limit the ability to write messages after the Nth time; Chat API supports time windows.
The integration itself determines the size of the time window. The timer will be reset after each incoming message, and count the time until the end of the time window.
Also the integration may also tell you that it needs to block sending messages after the time window has elapsed.
After disabling the ability to write a message, the user can select a template and send it.
Support for message templates
When sending a template from a card or bot, the integration will receive in the webhook the final text, the values of the placeholders that were replaced, and the template ID.
Here is an example of a template
And this is how Kommo interpret it
In the following articles, we will take a closer look at the technical part of the functionality described above, and the features of the Chat API, as well as give implementation examples.
Starting with Registering a new channel