API кнопки на сайте

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

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

window.amoSocialButtonConfig = {
  hidden: false, // скрыть кнопку при загрузке страницы
  color: '#000', // изменить цвет кнопки через, проигнорирует цвет настроенный в amoCRM

  onlinechat: {
    mode: 'widget', // еще может быть 'frame', об этом ниже

    locale: {
      extends: "ru",
      compose_placeholder: "Напишите ваш вопрос...",
    },

    theme: {
      header: false,
    },
  },
};

Остановимся более подробно на настройках онлайн-чата.

Отобразить окно чата в произвольном элементе страницы

window.amoSocialButtonConfig = {
  onlinechat: {
    mode: 'frame',
    container: '#custom_chat_holder',
  },
};

В данном случае при клике на иконку онлайн-чата в кнопке чат откроется не во всплывающем блоке рядом с кнопкой, а в произвольном элементе страницы, который указан в свойстве container.

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

Локализация

Полный список строк, доступных для локализации:

window.amoSocialButtonConfig = {
  onlinechat: {
    locale: {
      extends: 'ru',
      date_format: 'dd.MM.YYYY',
      time_format: 'HH:mm',
      compose_placeholder: 'Написать сообщение...',
      delivery_status_sending: 'Отправляется',
      delivery_status_sent: 'Отправлено',
      delivery_status_read: 'Прочитано',
      delivery_status_error: 'Ошибка',
      powered_by: 'Сделано в',
      new_messages: 'Новые сообщения'
    },
  },
};

Можно передать только нужные строки на перевод, при этом указать исходную локаль через extends, сейчас онлайн-чат “из коробки” поддерживает 4 локализации ru, en, es, pt.

Для date_format и time_format можно указать любые валидные значения из документации библиотеки date-fns.

Изменить внешний вид чата

window.amoSocialButtonConfig = {
  onlinechat: {
    theme: {
      background: 'yellow', // фон
      system_color: 'pink', // цвет системных текстов (статус доставки, дата)
      header: { // можно указать header: false, тогда он вообще не будет отрисован
        background: 'skyblue', // цвет фона верхней части чата
        color: 'black', // цвет текста верхней части
      },
      message: {
        outgoing_background: 'red', // фон сообщения пользователя
        outgoing_color: 'white', // цвет текста сообщения пользователя
        incoming_background: 'blue', // фон ответа оператора
        incoming_color: 'white', // цвет текста ответа оператора
      },
      compose: {
        height: 100, // минимальная высота в пикселях (максимальная 170px, изменить ее нельзя)
        button_background: 'black', // фон кнопки отправки
      }
    },
  },
};

Все цвета должны быть указаны в формате, который может быть обработан с помощью CSS в браузере (строковым значением как в примере, hex-код, rgb, rgba).

JavaScript методы

Для работы с чатом также предусмотрена специальная JavaScript-функция amoSocialButton, ее можно использовать в любом месте после подключения кода кнопки.

Поддерживаемые методы:

  • amoSocialButton(‘runChatShow’) – показать чат
  • amoSocialButton(‘runChatHide’) – скрыть чат

Колбэки

Также предусмотрены колбэки для реагирования на события, происходящие в кнопке и онлайн-чате.

amoSocialButton('onChatShow|onChatHide', function () {
  // при открытии на открытие/закрытие чата
});

amoSocialButton('onChatReady', function () {
  // чат проинициализирован,
  // можно с ним работать через JavaScript API
  amoSocialButton('runChatShow');
});

amoSocialButton('onButtonClick', function (service, link) {
  // при клике на кнопку
  // входящие параметры:
  // код сервиса
  // url ссылки, по которой кликнули
});

JS Параметры боте онлайн-чата

В бота онлайн-чата можно передать произвольные параметры с помощью метода amo_social_button.setMeta и, исходя из этих параметров, строить разные цепочки поведения бота. Например, пользователь авторизован у вас на сайте и вы хотели бы в поприветствовать его по имени. В таком случае на у вас на сайте нужно вызвать следующий код:

var USER_NAME = "<?= $username ?>";

amo_social_button.setMeta({
  bot_params: {
    username: USER_NAME
  }
});

В приветственном сообщении бота онлайн чата напишите Привет, {{bot_params.username}}.

Также бот онлайн-чата поддерживает условие с проверкой bot_params в первом шаге, поэтому легко можно реализовать, например, мультиязычность в приветственном сообщении. У себя на сайте необходимо пробросить параметр с текущей локалью пользователя:

var LOCALE = "ru"; // достаем локаль через geoip, либо API браузера

amo_social_button.setMeta({
  bot_params: {
    locale: LOCALE
  }
});

В боте ставим на первое место условие, в текстовой области условия добавляем следующий код:

// как видно, здесь массив,
// поэтому условий "и"
// может быть несколько
[
  {
    "term1": "{{bot_params.locale}}",
    "term2": "ru",
    "operation": "="
  }
]

Теперь если пользователь зашел на сайт и мы определили у него русский язык, то поведем его по ветке бота с русским языком.

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