JS SDK

Оглавление

JS методы и объекты для работы с amoCRM

В данном разделе описываются функции и объекты, которые служат для более простого обращения к окружению (информация о виджете, об авторизованном пользователе и т.д.), а также для вызова некоторых интерфейсных элементов.

Всплывающее уведомление

В системе реализована возможность выводить в правом нижнем углу окошко с уведомлением. Как пример использования можно назвать уведомление о входящем звонке вызываемой телефонией.

Для реализации данной функции можно использовать предусмотренный объект. В примере функция, созданная для работы с ним.

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;
    }

    AMOCRM.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);

Пример не только вызывает окошко уведомления, но и навешивает ссылку.

Уведомление об ошибке

Рекомендуем использовать подобные уведомления, если JS на странице производит какие-то фоновые действия (вызываемые скрыто от пользователя, не по его вызову). В таких случаях вы можете уведомлять пользователя о том, что что-то пошло не так и какие действия ему необходимо предпринять.

К примеру, вы разрабатываете виджет телефонии и в фоне соединяетесь с сервером для ожидания событий о входящих звонках. В какой-то момент вы поняли, что не можете установить соединение с вашим сервером и ожидаемый функционал не сработает. Лучше уведомить об этом пользователя сообщением об ошибке (с описанием причин) с указанием телефона технической поддержки.

От детальности проработки подобных сообщений сильно зависит сколько обращений о непонятных пользователю проблемах будет приходить в техническую поддержку. Если вы выведите пользователю сообщение о том, что он ввел не верный пароль, то вероятность звонка вам с непонятной ошибкой – меньше.

Объект очень похож на описанное выше уведомление, но выводит сообщение об ошибке. При этом иначе ведет себя функция закрытия окна, она запоминает в COOKIE пользователя событие закрытия и больше его не показывает.

var errors = AMOCRM.notifications,
    date_now = Math.ceil(Date.now() / 1000),
    header = self.get_settings().widget_code,
    text = 'error'
var n_data = {
        header: header, //код виджета
        text: '<p>' + text + '</p>', //текст уведомления об ошибке
        date: date_now //дата
    },
    callbacks = {
        done: function () {
            console.log('done');
        }, //успешно добавлено и сохранено AJAX done
        fail: function () {
            console.log('fail');
        }, //AJAX fail
        always: function () {
            console.log('always');
        } //вызывается всегда
    };

errors.add_error(n_data, callbacks);

Рассмотрим параметры подробнее:

  • header – (string) имя виджета будет отображаться в заголовке
  • text – (string) сообщение об ошибке
  • date – дата
  • callbacks – объект функций обратного вызова. При добавлении нового сообщения или ошибки AJAX запрос отправляется на сервер, который возвращает номер данного сообщения в случае успешного сохранения данных, в зависимости от успешности запроса срабатывает одна из переданных функций данного объекта

Метод для получения статуса online пользователей

Данный метод позволяет получать информацию об online статусах пользователей. Статус может быть true (если пользователь в сети) или false (если пользователя нет в сети).

Получение статуса online для всех пользователей

AMOCRM.sdk.showUserStatus() //объект со всеми id пользователей и их статусами
//Пример ответа:
{
    {
        id: 123456 ,
        online: true
    },
    {
        id: 123456 ,
        online: false
    }, ...
}

Для получения всех пользователей и их online статусов метод вызвается без флага и возвращает в объекте id всех пользователей и их online статусы.

Получение id всех пользователей в сети

AMOCRM.sdk.showUserStatus('online') // массив всех id пользователей online
//Пример ответа:
[123456 , 123457...]

Для получения списка всех пользователей, которые находятся в сети, данный метод необходимо вызвать с флагом "online". В этом случае он отдаст массив, содержащий id пользователей в сети.

Получение статуса online пользователя по его id

var id_user = 123456; //Уникальный идентификатор аккаунта
var status_user = AMOCRM.sdk.showUserStatus (id_user); // online статус пользователя (true или false)

Для получения статуса пользователя по его id необходимо вызвать метод c Уникальным идентификатором аккаунта. При этом данный метод вернет true (если пользователь в сети) или false (если пользователя нет в сети).

Метод для установки статуса звонка

Данный метод позволяет установить статус звонка. Входящий параметр boolean (true/false).

Установка статуса звонка

AMOCRM.sdk.setCallingStatus(boolean)

Метод для получения статуса звонка

Данный метод позволяет узнать статус телефонного разговора. Результат выполнения boolean.

Получение статуса звонка

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

Данный функционал необходим для того, чтобы не произошел обрыв разговора через виджет телефонии в момент обновления (отгрузки изменений) amoCRM.