Справочный центр
Справочный центр
Блокировка нежелательных звонков
Документация API
Интеграция с Битрикс24
Подключение интеграции Битрикс 24 Функциональность интеграции Виджет для звонков в Битрикс24 Импорт сотрудников из Bitrix24 Всплывающая карточка контакта в Битрикс 24 Персональный менеджер из Битрикс 24 Интеграция с Софтфоном UIS Распределение звонков по данным из Битрикс24 Исходящий звонок из Битрикс 24 по клику на номер Загрузка записей разговоров в Битрикс 24 Автоматическое создание Лида и Дела в Битрикс 24 Обработка потерянных звонков в интеграции с Битрикс 24 Назначение ответственного за потерянные обращения в Битрикс24 Автозвонки по событию из Битрикс 24 Единая точка входа в компанию. Фильтрация обращений, передаваемых в Битрикс24 Передача сделок из Битрикс24 в UIS Управление дополнительными полями в интеграции с Битрикс 24 Обработка звонков, заказанных через "Обратный звонок" в Битрикс24 Работа с Коллтрекингом Битрикс 24 Сквозная аналитика: Битрикс24
Интеграция с отраслевыми CRM
4Logist - CRM для транспорта и логистики APIX-DRIVE - онлайн коннектор сервисов и приложений Bnovo — система управления гостиницей, отелем, хостелом и апартаментами с подключением модулей и каналов онлайн-бронирования номеров Brizo - CRM система и управленческий учет для бизнеса DarWin - CRM и BPM система в одном решении DentalBase - облачная CRM для стоматологии DIKIDI – онлайн запись в салоны красоты E-Staff - CRM для подбора персонала EnvyCRM - универсальная CRM Flowlu - Управление проектами онлайн и CRM Gincore - облачная программа для сервисного центра или мастерской HOLLIHOP - CRM для учебных центров IDENT - Управление клиникой MEDIDEA - медицинская информационная система MegaCRM - управление продажами и заявками Neaktor - система управления проектами Okdesk - Help Desk система учета и управления заявками Omnidesk - сервис для поддержки и общения с клиентами SalesapCRM (S2) - облачная CRM для отдела продаж SalesPlatform – облачная CRM-система для автоматизации бизнеса SberCRM StomX - программа для стоматологии Synergy CRM - облачная CRM для отдела продаж U-ON Travel - CRM для турбизнеса WireCRM - модульная система для автоматизации продаж YCLIENTS - онлайн запись и автоматизация процессов YUcrm - CRM для недвижимости Автошкола-Контроль - облачный сервис для комплексной автоматизации автошколы АльфаCRM - CRM для детского учебного центра и школы Квартира.Бурмистр.Ру – автоматизация работы бизнеса в сфере ЖКХ (УК, ТСЖ) Клиентикс CRM МИС Medesk - медицинская CRM МИС MEDODS - медицинская CRM МойСклад - торговля, склад и CRM в облаке ПланФикс - платформа для создания системы управления предприятием Програмбанк.ФронтОфис - CRM для банков ПрофСалон - Программа для салонов красоты и бьюти индустрии РемОнлайн - программа для учета и автоматизации бизнеса в сфере услуг РосКвартал - АДС на 100% - современная диспетчерская для УК Юздеск - система автоматизации работы с заявками
Коллтрекинг и аналитика
Алгоритм коллтрекинга Настройка автоматического выбора номера Настройка рекламных кампаний Настройка динамического коллтрекинга Настройка сегментов посетителей Настройка событий (целей) Алгоритм учета посетителей Определение канала трафика Виды обращений Инструменты маркетолога: Сквозная аналитика Инструменты маркетолога: Анализ трафика Инструменты маркетолога: Аудитория Инструменты маркетолога: Содержание Список обращений: Цели Отчет Список сделок Свойства посетителя: добавление, проверка, удаление Что делать, если расходятся данные по посещениям Дополнительные настройки коллтрекинга: номера - ссылки для мобильной версии Автоматический выбор номера в динамически прогружаемых блоках Настройка промокода Интеграция с Universal Analytics Передача событий UIS и настройка целей в Universal Analytics Интеграция с OWOX BI Pipeline Интеграция с Яндекс.Директ Интеграция с Google AdWords Интеграция с Яндекс.Метрикой Настройка и передача статических UTM-меток для обращений Расчет охвата рекламных кампаний Инструменты атрибуции: Ассоциированные конверсии Инструменты атрибуции: Модели атрибуции Инструменты маркетолога: Воронки продаж Интеграция с VK Ads Интеграция с VK Leads Интеграция с myTarget
Справочный центр
Получить консультацию
Связаться

Справочник JS API

Дата публикации: 31 мая 2022

Пользователи могут использовать JavaScript API для решения следующих задач:

Для реализации дополнительных возможностей на сайте:

  • открытие форм связи онлайн-консультанта (чат, заявка) из любого места сайта пользователя. Получение дополнительной информации о посетителях сайта;

  • открытие формы и заказ обратного звонка через сайтфон;

  • присвоение свойств (например, посетителю, открывшему личный кабинет, присвоено свойство “действующий клиент”, открывшему тарифы - “потенциальный” и т.д.).

Получение дополнительных данных в отчетах:

  • данные о любом пользовательском событии на сайте (чтение книги, просмотр тарифов, открытие личного кабинете и т.д);

  • информация с любой формы заявки пользователя.

Работа с событиями

Отправка пользовательского события

Для отправки пользовательского события используется следующий метод:

Comagic.trackEvent(category, action, name, value);

Параметры:

Название Тип Описание
category text категория, обязательный параметр
action text действие, обязательный параметр
name text ярлык, необязательный параметр
value text значение, необязательный параметр


Пример использования:

Comagic.trackEvent('Offer', 'DownloadBook', 'CallTrackingBook', 'value');

Работа с баннером

Проверка наличия операторов онлайн

Для проверки наличия операторов онлайн используется метод:

Comagic.getOperatorStatus();

Метод возвращает true, если есть хотя бы один доступный оператор, иначе false.

Форма заявки

Для открытия формы заявки используется метод:

Comagic.openSiteRequestPanel();

Пользовательская форма заявки

Данные, полученные при использовании пользовательской формы заявки на сайте, можно отправить с помощью следующего метода:

Comagic.addOfflineRequest(req, callback);

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

Параметры:

Название Тип Описание
req {name: myName, email: myEmail, phone: myPhone, message: myMessage, is_sale: mySale, sale_cost: myCost, group_id: 12345, form_name: formName} Описание параметров: myName - тип text - имя посетителя, myEmail - тип text - адрес электронной почты посетителя, myPhone - тип text - телефон посетителя, myMessage - тип text - текст заявки и остальная информация, для которой нет отдельного поля, mySale - true - если это продажа; false - если не продажа (по умолчанию), group_id - id группы, в которую должна быть передана заявка, myCost - сумма сделки, form_name - имя пользовательской заявки. Если необходимо передать сумму сделки, то обязательно надо передать в параметре is_sale значение true.
callback "success": <Boolean>, "result": {"code": <String>}} Функция одного аргумента, которая будет вызвана после того, как сервер пришлет результат сохранения формы. Необязательный параметр.


Пример:

  • Обычная заявка:
Comagic.addOfflineRequest({
  name: 'Дмитрий',
  email: 'dmitry@comagic.ru',
  phone: '79123456789',
  message: 'Текст заявки...',
  group_id: 1234
});
  • Заявка, приведшая к продаже:
Comagic.addOfflineRequest({
  name: 'Дмитрий',
  email: 'dmitry@comagic.ru',
  phone: '79123456789',
  message: 'Онлайн заказ...',
  is_sale: true,
  sale_cost: '9999'
});
  • Заявка с использованием параметра callback:
Comagic.addOfflineRequest({"name": "My Name Is"}, function(o) {console.log(o);});
  • Заявка с указанием названия формы:
Comagic.addOfflineRequest({name: 'Дмитрий', email: 'dmitry@comagic.ru', phone: '79123456789', form_name: 'Название заявки', message: 'Текст заявки...'});

после успешного сохранения заявки в консоль браузера будет выведен результат:

Object {success: true, result: null}

Альтернативный способ отправки пользовательской заявки

  1. Перед отправкой заявки нужно получить аутентификационные данные виджета, используя метод JS API Comagic.getCredentials(). Метод возвращает объект:
{
  "site_key": "VcB4qqpO1WPSopO670cAbXwAH9Ryaw75",
  "visitor_id": 17258569,
  "hit_id": 546833568748,
  "session_id": 255544855,
  "consultant_server_url": "https://server.comagic.ru/" //базовая часть URL
}
  1. Передать полученные данные вместе с остальным данными формы.
  2. В серверном обработчике заявки сделать HTTP-запрос к сервису для добавления заявки.

Базовую часть URL жёстко прописывать нельзя. Её необходимо взять из данных п.1. Она может меняться.

POST https://server.comagic.ru/api/add_offline_message/
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Form Data //данные отформатированы для наглядности
site_key=VcB4qqpO1WPSopO670cAbXwAH9Ryaw75
&visitor_id=17258569
&hit_id=546833568748
&session_id=255544855
&name=John Smith
&email=no@email.adr
&phone=+79251234567
&text=Hello, world!
&is_sale=true
&sale_cost=10000

В ответ придёт флаг успешности добавления заявки (application/json):

{
  "success": true
}

Пример использования альтернативного способа отправки пользовательской заявки

Вариант с перезагрузкой страницы

Будем исходить из того, что на сайте уже установлен код вставки, подключена библиотека jQuery и есть форма обратной связи. Код простейшей формы обратной связи выглядит, примерно, так:

<form id='myform' action="/send.php" method="POST">
    <input type="text" name='name' value='' placeholder="Введите имя" /><br>
    <input type="text" name='phone' value='' placeholder="Введите номер телефона" /><br>
    <input type="text" name='email' value='' placeholder="Введите e-mail" /><br>
    <textarea name="text"></textarea><br>
    <input type='submit' />
</form>

Для того, чтобы отправить заявку, код формы нужно доработать: добавить служебные поля и обработчик на кнопку "Отправить":

<form id='myform' action="/send.php" method="POST">
    <input type="text" name='name' value='' placeholder="Введите имя" /><br>
    <input type="text" name='phone' value='' placeholder="Введите номер телефона" /><br>
    <input type="text" name='email' value='' placeholder="Введите e-mail" /><br>
    <textarea name="text"></textarea><br>
    <input type='button' value='Отправить' onclick="formSubmit()"/>
    <input type="hidden" name='site_key'/>
    <input type="hidden" name='visitor_id'/>
    <input type="hidden" name='hit_id'/>
    <input type="hidden" name='session_id'/>
    <input type="hidden" name='consultant_server_url'/>
</form>

В коде страницы или в отдельном JS-файле нужно написать функцию formSubmit(), которая будет вызываться каждый раз при клике на кнопку "Отправить":

function formSubmit() {
    var credentials = Comagic.getCredentials();
    for (var field in credentials) {
        if (credentials.hasOwnProperty(field)){
            $('[name='+field+']').val(credentials[field]);
        }
    }
    $('#myform').submit();
}

Этот код получает служебную информацию, сохраняет ее в невидимые служебные поля формы и отправляет форму на сервер.

Далее, нужно модифицировать код, который отвечает за обработку заявки на сервере. В нашем случае этот код находится в файле send.php:

<? /* Здесь код по умолчанию, связанный с обработкой заявки на серверной стороне. Например, отправка писем, или сохранение в базу данных. */ ?>
<?
    $url = $_POST['consultant_server_url'].'api/add_offline_message/';
          $data = array(
            'site_key' => $_POST['site_key'], //Значение без изменений из служебного поля site_key
            'visitor_id' => $_POST['visitor_id'], //Значение без изменений из служебного поля visitor_id
            'hit_id' => $_POST['hit_id'], //Значение без изменений из служебного поля hit_id
            'session_id' => $_POST['session_id'], //Значение без изменений из служебного поля session_id
            'name' => $_POST['name'], //Имя клиента
            'email' => $_POST['email'], //E-mail
            'phone' => $_POST['phone'], //Номер телефона
            'text' => $_POST['text'], //Текст заявки
            'is_sale' => true, //true, если это продажа
            'sale_cost' => 10000 //Сумма сделки. Если нужно передать сумму сделки, то is_sale обязательно равно true
            );
    /* Если все поля в html-разметке формы называются так же, как этого требует CoMagic, можно написать "$data = $_POST".
    В противном случае потребуются дополнительные преобразования. */
    $options = array( 'http' =>
        array(
            'header' => "Content-type: application/x-www-form-urlencoded; charset=UTF-8",
            'method' => "POST",
            'content' => http_build_query($data)
        )
    );
    print $options['http']['content'];
    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    $resultArray = json_decode($result, true);

    if ($result === false or $resultArray['success'] === false) {
        /* Здесь могут быть действия на тот случай, если отправка заявки завершилась ошибкой. */
    }
?>

Вариант с AJAX-запросом

HTML-разметка простейшей формы:

<form id='myform2'>
    <input type="text" name='name' value='' placeholder="Введите имя" /><br>
    <input type="text" name='phone' value='' placeholder="Введите номер телефона" /><br>
    <input type="text" name='email' value='' placeholder="Введите e-mail" /><br>
    <textarea name="text"></textarea><br>
    <input type='button' value='Отправить' onclick="sendAjaxSubmit()"/>
</form>

JS-код отправки AJAX-запроса:

function sendAjaxSubmit() {
    /* Здесь может быть проверка заполненных обязательных полей, валидация номера телефона и другие проверки. */
     $.ajax({
         url: 'sendAjax.php',
         method: 'POST',
         data: $('#myform2').serialize(),
         complete: function(response) {
             if (response.readyState === 4 && response.status === 200) {
                alert(response.responseText);
             }
         },
     })
}

PHP-код обработки полученного запроса:

<?
    /* Код для обработки пришедших данных, сохранение в БД или отправка заявки на почту. */
    $success = true; /* Переменная определяет, удалось ли сохранить заявку. */
    if ($success) {
        print 'Заявка успешно отправлена';
    } else {
        print 'Произошла непредвиденная ошибка';
    }
?>

Для того, чтобы отправить заявку в случае отправки заявки AJAX-запросом, модифицировать HTML-форму не нужно. Нужно модифицировать JS-код таким образом, чтобы получение служебной информации происходило перед отправкой запроса:

function sendAjaxSubmit() {
    /* Здесь может быть проверка заполненных обязательных полей, валидация номера телефона и
    другие проверки. */
    $.ajax({
        url: '/sendAjax.php',
        method: 'POST',
        data: $('#myform2').serialize(),
        complete: function(response) {
            if (response.readyState === 4 && response.status === 200) {
                alert(response.responseText);
            }
        },
        beforeSend: function(jqXHR, settings) {
            var credentials = Comagic.getCredentials();
            settings.data += '&' + $.param(credentials);
        }
    })
}

Код, который нужно выполнить на сервере. В данном случае он находится в файле sendAjax.php:

<?
    /* Здесь код по умолчанию, связанный с обработкой заявки на серверной стороне. Например, отправка писем, или сохранение в базу данных. */
?>
<?
    $success = true; /* Проверка того, что все выполнено корректно. */
    if ($success) {
        $url = $_POST['consultant_server_url'].'api/add_offline_message/';
        $data = array(
            'site_key' => $_POST['site_key'], //Значение без изменений из служебного поля site_key
            'visitor_id' => $_POST['visitor_id'], //Значение без изменений из служебного поля visitor_id
            'hit_id' => $_POST['hit_id'], //Значение без изменений из служебного поля hit_id
            'session_id' => $_POST['session_id'], //Значение без изменений из служебного поля session_id
            'name' => $_POST['name'], //Имя клиента
            'email' => $_POST['email'], //E-mail
            'phone' => $_POST['phone'], //Номер телефона
            'text' => $_POST['text'], //Текст заявки
            'is_sale' => true, //true, если это продажа
            'sale_cost' => 10000 //Сумма сделки. Если нужно передать сумму сделки, то is_sale обязательно равно true
        );
        /* Если все поля в html-разметке формы называются так же как этого требует comagic, можно написать "$data = $_POST".
        В противном случае потребуются дополнительные преобразования. */
        $options = array(
            'http' => array(
                'header' => "Content-type: application/x-www-form-urlencoded; charset=UTF-8",
                'method' => "POST",
                'content' => http_build_query($data)
            )
        );
        $context = stream_context_create($options);
        $result = file_get_contents($url, false, $context);
        $resultArray = json_decode($result, true);
        if ($result === false or $resultArray['success' === false]) {
            /* Обработка случая, если отправка заявки завершилась ошибкой. */
        } else {
            print 'Заявка успешно сохранена.';
        }
    } else {
        print 'Произошла непредвиденная ошибка';
    }
?>

Форма сайтфона

Для открытия нашей стандартной формы сайтфона используется метод:

ComagicWidget.openSitePhonePanel();

Капча для формы сайтфона

Comagic.Captcha.get_captcha(callback);

Параметры:

Название Тип Описание
callback {key: myKey, url: myURL} Возвращаемый ответ: myKey- ключ капчи, myURL - адрес картинки.


Пример:

Comagic.Captcha.get_captcha(function(resp){console.log(resp)});

Замена маски номера для формы сайтфона

Для того чтобы заменить стандартную маску ввода номера в сайтфоне и разрешить вводить номера в других форматах, в код вставки необходимо добавить строку:

__cs.push(["setUIPhoneMaskFormat", '1 () __-__']);

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

Пользовательская форма сайтфона

Помимо стандартных виджетов можно использовать любую свою форму для обратного звонка на сайте.

Для этого необходимо встроить вызов метода обратного звонка в свою форму с помощью JS API:

ComagicWidget.sitePhoneCall({captcha_key: <идентификатор капчи>, captcha_value: <решение капчи>, phone:<номер телефона>, delayed_call_time:<время звонка>, group_id:<id группы>}, callback);

Параметры:

Название Тип Описание
captcha_key text Идентификатор капчи. Обязательный, если в настройках обратного звонка включена капча.
captcha_value text Решение капчи (то, что ввел посетитель на форме): взять результат myURL из метода Captcha.get_captcha(), перейти по ссылке, увидеть 4 цифры. Обязательный, если в настройках обратного звонка включена капча.
phone text Номер телефона посетителя. Обязательный.
delayed_call_time text Время совершения звонка в миллисекундах по UTC.
group_id text ID группы сотрудников, в которую будет направлен звонок.
callback {"success": <Boolean>, "result":{status: <Integer>, code: <String>}} Возвращаемый ответ, необязательный (но желательный). Если его не задать, то функция отработает аналогично вызову из стандартной формы сайтфона и покажет всплывающее уведомление с результатом. Параметры: success: true - успешно, false - не успешно; result - результат вызова: status - статус вызова.


Возможные статусы:

Код Значение
0 успешно, звонок отправлен на платформу
1 капча введена неверно
2 не задан сценарий обработки обратного звонка
3 ошибка платформы
4 исчерпан лимит на количество вызовов в минуту (не более 10 звонков)


Пример использования:

ComagicWidget.sitePhoneCall({captcha_key: 'jwgtGYZDYTA...4pBEWRx', captcha_value: '8315', phone:'79101234567', delayed_call_time: 1508927547000 , group_id: '16587'}, function(resp){console.log(resp)});

Форма чата

При вызове следующего метода, если есть операторы online, открывается форма чата:

Comagic.openChatWindow();

Если ни одного оператора нет online, то открывается форма заявки.

Работа с посетителем

Получение ID посетителя

Для получения ID посетителя используется следующий метод:

Comagic.getVisitorId();

Получение ID сессии посетителя

Для получения ID сессии посетителя используется следующий метод:

Comagic.getSessionId()

Добавление информации о посетителе

Для добавлении информации о посетителе используется следующий метод:

Comagic.addVisitorInfo({name:'myName', phone:'myPhone', email:'myEmail'});

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

Для успешного вызова метода должен быть заполнен хотя бы один параметр.
Все другие параметры будут проигнорированы

Параметры:

Название Параметры Описание
req {name: myName, email: myEmail, phone: myPhone} myName - тип text - имя посетителя (перезаписываемый)
myEmail - тип text - адрес электронной почты посетителя (добавляется уникальный)
myPhone - тип text - телефон посетителя (добавляется уникальный)
callback "success": <Boolean> Функция одного аргумента, которая будет вызвана после того, как сервер пришлет результат сохранения формы. Необязательный параметр.


Пример:

Comagic.addVisitorInfo({name:'Test', phone:'79000000000', email:'myemail@axample.com'},function(resp){console.log(resp)})

Альтернативный способ добавления информации о посетителе

Будем исходить из того, что на сайте уже установлен код вставки, подключена библиотека jQuery

  • Перед отправкой информации о посетителе нужно получить аутентификационные данные, используя метод JS API Comagic.getCredentials().

Метод возвращает объект:

{
  "site_key": "VcB4qqpO1WPSopO670cAbXwAH9Ryaw75",
  "visitor_id": 17258569,
  "hit_id": 546833568748,
  "session_id": 255544855,
  "consultant_server_url": "https://server.comagic.ru/" // Этот URL нам не нужен
}
  • Передать полученные данные вместе с остальным данными формы.

Параметры:

url - https://tracker.comagic.ru/vc/s/
параметры из запроса Comagic.getCredentials():
sk=site_key
ci=comagic_id
hi=hit_id
vp=телефон
vn=имя
ve=емейл
s=1 убирает вывод системных полей в ответе (возвращается только success: true)

Пример

https://tracker.comagic.ru/vc/s/?sk=nS5lMAgURPyUQXVyBgguFy0AvIRdbfdy&ci=2032047566.3117192853.1555675484&hi=9228054013&vn=new_user

Добавление свойства посетителю

Для присвоения свойства или его значения используется следующий метод:

Comagic.setProperty(name, value);

Параметры:

Название Тип Описание
name text Имя свойства, которое должно быть присвоено посетителю
value text Значение свойства (необязательный параметр)


Примеры:

Свойство тип посетителя со значением Потенциальный устанавливается следующим образом:

Comagic.setProperty('Тип посетителя', 'Потенциальный');

Свойство Действующий клиент (без значения) устанавливается следующим образом:

Comagic.setProperty('Действующий клиент');

Проверка наличия свойства у посетителя

Для проверки наличия свойства у посетиетля используется следующий метод:

Comagic.hasProperty(name, callback);

Параметры:

Название Тип Описание
name text Имя свойства, которое должно быть присвоено посетителю
callback {"success": <Boolean>,"result": <Boolean>,} Возвращаемый ответ. success: true - метод обработан успешно, false - ошибка; result: true - свойство name установлено false - свойство name не установлено


Пример:

Comagic.hasProperty('Действующий клиент', callback);
Comagic.hasProperty('Действующий клиент', function(resp){console.log(resp)});

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

Для получения значения свойства у посетителя используется следующий метод:

Comagic.getProperty(name, callback);

Параметры:

Название Тип Описание
name text Имя свойства, которое должно быть присвоено посетителю
callback {"success": <Boolean>, "result": <value>,} Возвращаемый ответ. success: true - метод обработан успешно, false - ошибка; result: value - значение свойства name, false - свойство name не установлено


Пример:

Comagic.getProperty('Тип клиента', callback);
Comagic.getProperty('Действующий клиент', function(resp){console.log(resp)});

Удаление свойства посетителя

Для удаления свойства, заданного посетителю, используется следующий метод:

Comagic.deleteProperty(name);

Параметры:

Название Тип Описание
name text Имя свойства, которое должно быть удалено
Эта статья была полезна для людей. Эта статья помогла Вам?
Да, помогла!
Вопрос не решён
Не пропустите новости. Будем на связи!
Получать новости
Спасибо за обращение
Понятно