Kommo has the ability to display a notification window in the lower left corner. An example of use is a notification about an incoming call by the calling telephony.

There are two main ways to create call notifications: creating call notification via API and via JavaScript widget.

Create call notification via API

You can create a call notification via API. This method will automatically find an entity (contact/company/lead) by the passed phone number and display a notification for the desired employee with the entity name according to the following priority:

• If the contact/company has one active lead, then the lead will be shown.
• If the contact/company has either more than one active lead or no related leads, then the contact/company name will be shown.

If such a number is not yet in the system, then the notification will offer to create a contact with this number.

👍

This method will allow you to avoid making unnecessary requests to search for entities by phone number via API which significantly optimizes the work of the VoIP integration.

Create call notification via JS widget

Another way is to create notifications using the JS part of the widget. Upon receiving an incoming call, the virtual PBX queries Kommo via the Get contacts API method, passing the phone number in the ?query={phone_number} parameter to request information about the calling contact. This contact must exist in Kommo and the corresponding user must have rights to view the desired contact card.

A minimal timeout must be set for processing the request to avoid call issues in case of degraded connectivity between the PBX and Kommo.

To deliver incoming call information to the client-side JS script, web-socket technology is typically used. This involves establishing a persistent connection and subscribing to events. Alternatively, periodic polling via JS can be used — by regularly loading a JS file from an external server, which returns an array indicating the current call status (e.g., incoming call, idle etc. for each users internal number).

The choice between these methods depends on whether the virtual PBX supports web-sockets. It is also important to map internal phone numbers to Kommo users authorized to view the interface.

Example of an incoming call card

In order to implement an incoming call card, you can use the object APP.notifications.add_call(call_params) . In the example, a function is created to work with it. In order to retrieve contact information using only the incoming call phone number, you can use the Get contacts method with the ?query={phone_number} parameter.

const addCallNotification = async (notificationOptions) => {
  const {
    text,
    from,
    to,
    duration,
    link,
    date = Math.ceil(Date.now() / 1000),
    element: entity,
    clickLink,
  } = notificationOptions;

  /**
   * If necessary, customize or modify the notification parameters.
   */
  const possibleCallers = await searchContactByPhone(from);

  const notificationText = possibleCallers.reduce((acc, contact, index) => {
    const { name } = contact;

    return `${index ? acc : `${acc}, `}${name}`;
  }, "Phone number is linked to: ");

  const notification = {
    text: notificationText,
    from,
    to,
    duration,
    link,
    date,
    element: entity,
    click_link: clickLink,
  };

  /**
   * Adds a notification with the defined options.
   */
  APP.notifications.add_call(notification);
};

In order to get a contact information by the phone number of an incoming call, you can pass Get contacts list request with ?query={phone_number} parameter:

const FALLBACK_FN = () => undefined;
const PHONE_CUSTOM_FIELD_CODE = "PHONE";

const searchContactByPhone = async (phone, callbacks = {}) => {
  const { onSuccess = FALLBACK_FN, onError = FALLBACK_FN } = callbacks;

  if (!phone) {
    return;
  }

  try {
    const contactsData = await $.ajax(`/api/v4/contacts?query=${phone}`, {
      method: "GET",
    });

    onSuccess(contactsData);

    return contactsData._embedded.contacts;
  } catch (error) {
    onError(error);
  }
};

Widget location

It’s important to remember that you must declare the widget connection scope in the manifest.json file. To enable the incoming call card feature, it is recommended to set the scope to everywhere. This way, your widget will be triggered in any area of Kommo, allowing you to receive incoming call notifications regardless of what the user is currently doing in Kommo. You can read more about connection scopes [here].

"locations": [ "everywhere"]

Create error notification

In order to notify users about issues occurring in background processes, a separate JavaScript object should be used. When invoked, this object will display an error notification to the user, for example, informing them about a failed connection to the server.

It is recommended to use such notifications whenever JavaScript on the page performs background operations (triggered silently without direct user action). In these cases, you can inform the user that something has gone wrong and provide guidance on the necessary steps they should take.