Call notification

Kommo provides many ways to show a notification about an (incoming/outgoing) (ongoing/completed) call.

Add call event

Show notification about call

Add completed call notification

Web sockets 

Add call event

Creating a notification using the public API method POST /api/v2/events. This method performs a search for the caller ID and creates a notification, connected to the card with this phone number if it exists, and if not linked to create a new contact.

The notification will appear in the interface, and will be transmitted over all active delivery channels, which means it will appear in the notification center (the bell icon).

Every time you create a call notification using this method, it will appear in the notification center.


If more than one entity were assigned this phone number, then the method will return only one entity (lead, company, contact or customer).

The method first searches for a contact associated with this phone number. If there is more than one, then the following points are considered:

  • The oldest contact will be considered.
  • If there is a one and only one active lead/customer connected to this contact, this lead/customer will be returned. The name of the caller will be the lead’s/customer’s name if it is set.
  • If there is more than one active lead/customer or there is none, the contact will be returned. The name of the caller will be the contact name.

If no contact is found, the algorithm repeats the search for a company with the same considerations.

Otherwise it will return an empty array.

Note: This method uses only the last eight digits of the phone number for searching.

Method URL

POST /api/v2/events/

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.


Content-Type: application/json

Example of a request body

 "add": [
   "type": "phone_call",
   "phone_number": "+18305703077",
   "users": [8320148,8375357]

Body parameters

Parameter Description
type Event type: in our case phone_call
phone_number The phone number
users List of users where the notification will be displayed

Notification in the interface


Notifications in the notification center


Note that this is a notification about a call in general. There is no difference between incoming and outgoing calls in this method.

Example of the response

   "_links": {
       "self": {
           "href": "/api/v2/events/"
   "_embedded": {
       "items": [
               "element_type": 2,
               "element_id": 5756100,
               "uid": "bb371363-25f6-4c60-8942-c0e00d2f073e",
               "phone_number": "+18305803077",
               "query_string": "05803077"

Response parameters

Parameter Description
_embedded An array containing information about the successfully returned entity
_embedded[items][0][id] Unique identifier of the entity
_embedded[items][0][element_type] Entity type (1 for contacts, 2 for leads, 3 for companies, 12 for customers)
_embedded[items][0][element_id] Entity ID
_embedded[items][0][phone_number] The phone number that we requested
_embedded[items][0][query_string] The last 8 digits from the phone number which are compared.

Show notification about a call

The method “show_notification” from the notification center allows you to display a pop-up notification about a call. This method can be implemented in the widget. If you use this function, the notification will be displayed only in the interface and will not appear in the notification center.

Method name



Parameter Required Description
text Yes Message description
text[header] Yes Notification Header
text[text] Yes Text message
date No Date in timestamp format
type Yes Type of pop-up notification. Use value: ​​call


var notification = {
  text: {
    header: "Outgoing call",
    text: "Dialing +18305803077"
  type: "call"



Add notification about a completed call

You can use the “add_call” method also provided by the notification center to display a notification about a completed call, providing the duration and the recording if they are available.

The notification will appear in the interface, and will be transmitted over all active delivery channels, which means it will appear in the notification center.

Method name



Parameter Required Description
text Yes The text message that will be displayed in the notification.
date No Date in timestamp format
from No From whom the call was performed. If a contact with the phone number exists, the contact name or phone number is used, if not, just the phone number is used.
to No Manager name or extension number of the manager who received the incoming call.
element No An object describing the entity to which the redirection will occur when clicking on the pop-up call notification. Yes Entity ID
element.type Yes Entity type: contact, lead or company

Note: The element id is the primary key in this notification entity. Notification center keeps only  one instance of a call with an element id. This means that when more than one call notification with the same element id is done using this method, only the last notification is shown in the notification center.

Here is an example of how to implement it in the frontend.

add_call_notify = function(data){
var w_name = self.i18n('widget').name,
	lang = self.i18n('settings'),
	n_data = {
		from: data.from,
		duration: data.duration,
		text: w_name + ': ' + data.text,
		element: data.element
	/* Check if there is an incoming caller’s contact id in the system */
	if ( > 0){
		//If there is an already existing id , create a link for this contact in Kommo
		text = 'Call from '' Go to the contact card';
		n_data.text = text;
		n_data.from = data.from;
		if (n_data.from.length < 4){
			//Check for an internal number
			n_data.header = 'Internal number: '+data.from+';
		else {
			n_data.header = 'Incoming call: '+data.from+';

Notification in the interface


Notification in the notification center

It is important to remember that you must declare the widget’s scope in manifest.json. To perform the function of the incoming call card, it is recommended to set the area everywhere. By specifying that your widget will fire in any area of Kommo, and this will allow you to receive notifications of an incoming call, regardless of what work the user is doing in Kommo. Read more about connection areas.

/* manifest.json */
 "locations": [ "everywhere" ]

Web sockets

To deliver information about an incoming call to a client-side JS script, web sockets technologies are usually used when a permanent connection and event subscription are established between the client and the server. You can use the technology of periodic calls through JS to a third-party server. To do this, once every few seconds on the client side, a JS file is loaded from the target server, where an array with the channel state is defined (there is a call, there is no call for a specific employee extension).
The choice of method depends on the technical capability on the side of the virtual PBX to support a web-sockets connection. At the same time, it is necessary to take into account the extension numbers of employees and their correspondence to users authorized in Kommo.