API CRM Plugin

Оглавление

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

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

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

  onlinechat: {
    mode: 'widget', // еще может быть 'frame', об этом ниже
    user_id: '', // id пользователя онлайн-чата (необязательный параметр)

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

Изменить пользователя чата

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

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

  1. Авторизованный в своей учетной записи клиент интернет-магазина ведет диалог в онлайн-чате (куда предварительно был передан user_id)
  2. Тот же клиент решает зайти с другого устройства (например, с мобильного телефона)
  3. После авторизации клиента в своей учетной записи, передаем тот же самый user_id
  4. При открытии окна онлайн-чата клиентом, появится уже существующий диалог со всей историей переписки.

Настоятельно рекомендуем для защиты от получения доступа к беседе путем перебора id, хешировать user_id с помощью любого, удобного для вас алгоритма шифрования (SHA-256, MD-5 и т.п.)

window.amoSocialButtonConfig = {
  onlinechat: {
    user_id: 'abc123'
  },
};

JavaScript методы

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

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

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

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

Для уничтожения экземпляра предусмотрен метод:

  • amoSocialButton(‘runDestroy’) – удалит текущий экземпляр кнопки

Колбэки

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

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

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

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

amoSocialButton('onConversationsChange', function (conversations) {
  // при изменении бесед
  // 
  // при выключенных мультибеседах ивент сработает 1 раз, 
  // где conversations будет false
  //
  // входящие параметры:
  // conversations - массив видимых бесед 

  // формат беседы
  //
  // {
  //   name: 'A123',
  //   is_closed: true | false,
  //   last_message: {
  //     media: {
  //       url: 'https://path_to_resource.mp4',
  //       thumbnail: 'https://path_to_preview.jpg',
  //     } | undefined,
  //     created_at: 1655283158457,
  //     is_out: true | false,
  //     text: 'Hello',
  //     type: 'text' | 'video' | 'photo',
  //     author: {
  //       name: author.name,
  //     } | undefined,
  //   },
  // },
});

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": "="
  }
]

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

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

Отправка ключевого действия с помощью хука

Чтобы отправить собственный хук для срабатывания ключевого действия необходимо в любом месте после подключения кода кнопки, либо по какому-то браузерному событию (например, по клику на кнопку) выполнить следующий код:

amoSocialButton('sendKeyActionHook', 'Название хука'); // которое вы задали в условии срабатывания ключевого действия в пункте "собственный хук"