JS SDK

JS methods and objects for working with Kommo

This section describes functions and objects that serve to more easily access the environment (information about the widget, the authorized user, etc.), as well as for calling some interface elements.

Pop-up notification

The system has the ability to display a window in the lower right corner with a notification. As an example of use, you can call an incoming call notification by the called telephony.

To implement this function, you can use the provided object. In the example, the function 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 box, but also links the link.

Custom search when filling the field type “legal entity”

In the system the opportunity is realized to use 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 in the APP.widgets.legal_handlers array a function that will return ajax. 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 JS on the page performs some background actions (called hidden from the user, not by his call). In such cases, you can notify the user that something went wrong and what actions he needs to take.

For example, you develop a telephony widget and connect to the server in the background to wait for events about incoming calls. At some point you realized that you can not connect to your server and the expected functionality will not work. It is better to notify the user of this error message (with a description of the reasons) with the phone number of technical support.

From the detail of the development of such messages depends on how many calls about incomprehensible user problems will come in technical support. If you display a message to the user that he entered an incorrect password, then the probability of a call with an incomprehensible error is smaller.

The object is very similar to the above notification, but displays an error message. In this case, the closing function of the window behaves differently, it remembers the closing event in the user COOKIE and does not show it any more.

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:'
'+text+'
',// 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);

Consider the parameters in more detail:

  • header – (string) the name of the widget will be displayed in the title

  • text – (string) error message

  • date – date

  • callbacks object callback functions. When you add a new message or AJAX error, the request is sent to the server, which returns the number of this message if the data is successfully saved, depending on the success of the request, one of the transferred functions of this object

The Modal object for working with the modal window

To work with it, it must be connected in the script.js file

This example shows how to use the modal window object Modal

A separate example is given below.

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
  }, ...
}

To get all users and their online statuses, the method is called without a flag and returns all users and their online statuses in the id object.

Getting the id of all users on the network

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

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

Getting the status of an online user by his id

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

To get the status of a user by its id, you must call the method with the unique account identifier. This method returns true (if the user is on the network) or false (if the user is not on the network)

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, an incorrect flag was given, then the function will work as well as without parameters, returning the object with all id and their online statuses.

SDK Card