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.

Algorithm

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.

Headers

Content-Type: application/json

Example of a request body

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

Body parameters

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

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

show_notification()

Parameters

Example

var notification = {
  text: {
    header: "Outgoing call",
    text: "Dialing +18305803077"
  },
  type: "call"
};
APP.notifications.show_notification(notification);

Result

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

add_call()

Parameters

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,
		to: data.to,
		duration: data.duration,
		link: data.link,
		text: w_name + ': ' + data.text,
		date: Date.now(),
		element: data.element
	};
	/* Check if there is an incoming caller’s contact id in the system */
	if (n_data.element.id > 0){
		//If there is an already existing id , create a link for this contact in Kommo
		text = 'Call from '+n_data.element.name+' 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+';
		}
	}
	APP.notifications.add_call(n_data);
};

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.