JS SDK

JS methods and objects for working with Kommo

This section provides details on how to access the environment easily, including widget information and authorized user information, as well as how to call various interface elements.

Pop-up notification

One of the features the system offers is the ability to display a notification window in the bottom right corner of the screen. This feature can be used to notify users of an incoming call through VoIP.

You can use the provided object to accomplish this. In the following example, a function has been created to work with such an object.

self.add_call_notify = function(mess){
    const w_name = self.i18n('widget').name,
        date_now = Math.ceil(Date.now()/1000),
        lang = self.i18n('settings'),
        n_data = {
            from: mess.from,
            to: mess.to,
            duration: mess.duration,
            link: mess.link,
            text: w_name + ': ' + mess.text,
            date: date_now
        };
 
    if (mess.element && mess.element.id && mess.element.type){
        n_data.element = mess.element;
    }
   
    APP.notifications.add_call(n_data);
};
 
/*---------------------------------------*/
const notify_data={};
notify_data.from = '+7 (999) 111 22 33';
notify_data.to = 'User Name';
notify_data.duration = 65;
notify_data.link = 'https://example.com/dialog.mp3';
notify_data.text = 'Widget text';
notify_data.element = { id: 1003619, type: "contact" };
 
self.add_call_notify(notify_data);

In the example the function not only calls the notification window but also adds a link.

Error Notification

If JavaScript performs background actions that are hidden from the user, it's important to notify them about any issues that may arise. By doing so, you can help them take the necessary actions to fix the problem and avoid frustration.

For example, if you are developing a VoIP widget that, being connected to the server in the background, waits for incoming call events, it's important to notify the user if there's an issue connecting to the server. By providing a clear error message and a description of the issue, you can help the user understand what's going on and even provide them with technical support contact information.

Similarly, if a user enters the wrong password, it's better to notify them of the error upfront. This way, they won't be left wondering why the expected functionality isn't working.

The following object ,similar to the notification described above, can help with this. It displays an error message and stores the closing event in the user's cookie, ensuring that the user won't be bothered with the same notification again.

const  errors = APP.notifications,
    date_now = Math.ceil(Date.now()/1000),
    header = self.get_settings().widget_code,
    text = 'error'
    const n_data = {
                header: header, // widget code  
                text:'<p>'+text+'</p>',// error message text
                date: date_now // /date
            },
    callbacks = { done: function(){console.log('done');}, //successfully added and saved AJAX done
                  fail: function(){console.log('fail');}, //AJAX fail
                  always: function(){console.log('always');} // always called
                };
 
    errors.add_error(n_data,callbacks);
  • header (string) - widget name that will be displayed in the title
  • text(string) - error message
  • date - date
  • callbacks(object) - in the process of sending a new message or handling an AJAX error, a request is sent to the server. If the data is saved successfully, the server returns the number of the message. Depending on whether the request was successful or not, one of the passed functions of the object is triggered.

User online status

This method allows you to obtain information about user online statuses. The status can be true (if the user is online) or false (if the user is offline).

Obtaining online status for all users

APP.sdk.showUserStatus() //object with all user IDs and their statuses  
//Example response:
{
    {
        id: 123456 ,
        online: true
    },
    {
        id: 123456 ,
        online: false
    }, ...
}

To obtain all users and their online statuses, the method is called without a flag and returns an object with all user IDs and their online statuses.

Getting the IDs of all users on the network

APP.sdk.showUserStatus(‘online’) // array of all online user IDs\
//Example response:
[123456 , 123457...]

To get a list of all users who are online, this method must be called with the “online” flag. In this case, it will return an array containing the IDs of users online.

Getting a user's online status by their ID

const id_user = 123456; // Unique account ID
const status_user = APP.sdk.showUserStatus (id_user); // user's online status (true or false)

To obtain a user's status by their ID, you need to call the method with a unique account identifier. This method will return true (if the user is online) or false (if the user is not online).

Setting call status

This method allows you to set the call status. Incoming parameter boolean (true/false).

Setting call status

APP.sdk.setCallingStatus(boolean)

Obtaining call status

This method allows you to find out the status of a phone call. The result of execution is boolean.

Getting the call status

if (APP.sdk.getCallingStatus()) {  
    // code
} else {
    // code
}

This functionality is necessary to prevent the call from being interrupted via the telephony widget when Kommo is updated (changes are shipped).