JS SDK

JS methods and objects for working with Kommo

This section describes functions and objects that allow easier access to the environment (widget information, an authorized user, etc.) and for calling some interface elements.

Pop-up notification

The system can display a notification window in the lower right corner. As an example of use, you can call the notification of an incoming call called VoIP.

To implement this function, you can use the provided object. In the example, a function was created to work with it.

self.add_call_notify = function(mess){
    var 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);
};
 
/*---------------------------------------*/
var 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);

The example not only calls the notification window but also connects a link.

Custom search when filling in the field type “legal entity”

In the system, the opportunity is realized to use the custom search of legal entities when filling a field of type legal entity

To implement this function, you can use the provided method. To do this, put a function that will return Ajax in the APP.widgets.legal_handlers array. Ajax should return an array of objects of the following structure:

{
    name: ''QSOFT LLC',
    inn: '5009051111',
    kpp: '500901001',
    ogrn: '1065009000187',
    type: '1',
    address: '222 COLUMBUS AVE SUITE 407 SAN FRANCISCO, CA',
}

Implementation example:

APP.widgets.legal_handlers = [function(data) {
    var def = $.Deferred();
 
    $.ajax({
        type: 'POST',
        url: 'http://www.example.com/',
        dataType: 'json',
        data: data
    }).done(_.bind(function (response) {
        var res;
       
       res = _.map(response._embedded.items, function(item) {
           return {
               name: item.name,
               inn: item.inn,
               kpp: item.kpp,
               ogrn: item.ogrn,
               type: item.type,
               address: item.address
           };
       });
 
       this.def.resolve(res);
    }, {def: def}))
    .fail(_.bind(def.reject, def, []));;
 
    return def.promise();
}];

Error Notification

We recommend using such notifications if the JS on the page performs some background actions (called hidden from the user, not on his call). In such cases, you can notify the user that something has gone wrong and what actions he needs to take.

For example, you are developing a VoIP widget and connecting to the server in the background to wait for incoming call events. At some point, you realized that you could not establish a connection with your server, and the expected functionality would not work. It is better to notify the user about this with an error message (with a description of the reasons) indicating the phone number of technical support.

If you display a message to the user stating that he entered the wrong password, then the likelihood of a call to you with an incomprehensible error is less.

The object is similar to the notification described above but displays an error message. At the same time, the window closing function behaves differently; it remembers the closing event in the user’s COOKIE and does not show it anymore.

var  errors = APP.notifications,
    date_now = Math.ceil(Date.now()/1000),
    header = self.get_settings().widget_code,
    text = 'error'
    var 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);

In this example, the parameters represent:

header: (string) The widget name will be displayed in the title
text: (string) Error message
date: date
callbacks: an object of callback functions. When a new message or an AJAX error is added, a request is sent to the server, which returns the number of this message if the data is saved successfully; depending on the success of the request, one of the passed functions of this object is triggered.

The Modal object for working with the modal window

The modal object must be connected in the script.js file.

This example shows how to use the modal window object Modal

define(['jquery','lib/components/base/modal'], function($, Modal){
  var CustomWidget = function () {
    this.callbacks = {
      // . . .
      bind_actions: function(){
        //.  .  .
        var data ='&lth1&gtTest&lt/h1&gt&ltp&gtSome text&lt/p&gt';
        modal = new Modal({
          class_name: 'modal-window',
          init: function ($modal_body) {
            var $this = $(this);
            $modal_body
              .trigger('modal:loaded') // launches a modal window
              .html(data)
              .trigger('modal:centrify')  // configures the modal window
              .append('&ltspan class="modal-body__close"&gt&ltspan class="icon icon-modal-    close"&gt&lt/span&gt&lt/span&gt');
          },
          destroy: function () {
          }
        });
        //.  .  .
        return true;
      }
    }
  }
  return CustomWidget;
});

To work with a modal window object, you need to connect it via require (define at the beginning of script.js) and pass parameters: class_name, init(), destroy(). In init, the data to display in the modal window, and the trigger events are passed in order to start the methods of the Modal object and display the modal window in the DOM.

Method for obtaining the status of online users

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

Getting online status for all users

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

The method is called without parameters and returns all users and their online statuses in the id object.

Getting the id of all online users

APP.sdk.showUserStatus('online')// array of all id users online
// Example response:
[123456, 123457...]

Calling this method with the “online” flag will list all online users. In this case, the list contains the ids of online users.

Getting the status of an online user by their id

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

To get a user’s status by its id, you must call the method with the unique account identifier.

This method returns true (if the user is online) or false (if the user is not online).

Error processing

APP.notifications.show_user_status(‘someString’) // object with all users id and status

If an incorrect user id was entered, an error was made while writing the flag, and an incorrect flag was given. The function will work as well as without parameters, returning the object with all id and their online statuses.

SDK Card