Черновик документации API для управления виджетом Чатры

chatra-api-draft.md

Вечная привязка к залогиненному пользователю

Чтобы привязать чат к узнанному на сайте пользователю, задайте свойство clientId в объекте ChatraSetup перед кодом виджета:

<script>
  ChatraSetup = {
    clientId: 'sf87fasdfFF8' // любая уникальная строка
  };
</script>

<script>
    // Код со страницы «Установка виджета»
</script>

Важно, что свойство clientId должно быть уникальным и секретным, потому что, зная его, можно получить доступ к переписке. Лучше использовать специально сгенерированный ключ, а не открытые id, username или email.

Передача в чат кастомных полей

Чтобы передать в чат какие-то сведения о пользователе используйте объект ChatraIntegration:

<script>
  ChatraIntegration = {
    // основные поля
    name: 'Иванушка',
    email: '[email protected]',
    notes: 'Ищет то, не знаю что...',

    // произвольные поля    
    'Что делает': 'Лежит на печи'
  };
</script>

<script>
    // Код со страницы «Установка виджета»
</script>

В ChatraIntegration можно передавать любые свойства-строки, все они попадут в правую инфо-панель в операторском приложении:

Открыть чат по клику на собственной кнопке

<script>
window.ChatraSetup = {
    onInit: function() {
       // Чатра загрузилась
 
       // Вешаем событие на клик по кнопке
        $('#custom-chatra-button').on('click', function () {
          Chatra.openChat();
        });
    }
}
</script>
<script>
  // Код виджета с ChatraID
</script>
 
...
 
<!-- Кастомная кнопка в любом месте страницы -->
<button id="custom-chatra-button">Открыть чат</button>

Отключить кнопку чата на мобильных устройствах

<style>
  #chatra.chatra--mobile {
    display: none !important;
  }
</style>
<script>
  // Код виджета с ChatraID
</script>

Встроить чат в произвольный блок на странице

Для этого нужно указать свойства mode и injectTo в объектe ChatraSetup перед вызовом виджета:

<script>
  ChatraSetup = {
    mode: 'frame',
    injectTo: 'chatra-wrapper' // айди блока, куда встроить чат
  };
</script>

<script>
    // Код со страницы «Установка виджета»
</script>

Остаётся вставить блок <div id="chatra-wrapper"></div> в нужное место на странице и задать ему ширину с высотой. Должно получиться примерно так: http://share.artpolikarpov.ru/1e0PQ

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

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