Chatix-core NPM

Логотип Chatix

Chatix Core

Chatix Core - JS SDK которое позволяет создавать встроенные в ваше web-приложение чаты и использовать платформу Chatix как поставщика серверной части. Chatix занимается обслуживанием сетевого соединения и хранением данных, а вам остается только отобразить эти данные вашему пользователю.

Первые шаги

Прежде всего вам нужен аккаунт Chatix, чтобы вы смогли использовать этот SDK на своем сайте. Посетите сайт chatix.io чтобы создать бесплатный аккаунт и получиить свой website_id. Этот идентификатор определяет ваш сайт в Chatix и это обязтельный атрибут для конструктора SDK.

Когда вы получите свой website_id, вы сможете приступить к разработке чатов с Chatix Core.

Установка

Установите пакет chatix-core с помощью своего пакетного менеджера
Импортируйте ChatixCore в свое приложение import ChatixCore from 'chatix-core'. Важно: В приложении должна быть только одна сущность SDK.
Создайте экземпляр ChatixCore и передайте в конструктор свой идентификатор let core = new ChatixCore(websiteId);. Подробная документация по свойствам и методам SDK будет рассказана ниже.
Начните соединение вызовом core.start();

Основной класс ChatixCore

ChatixCore - главный объект. Все должно быть сделано с использованием этого объекта. У вас есть доступ к его свойствам и методам, чтобы разработать собственный интерфейс. new ChatixCore(websiteId, visitorId);

Аргумент	Тип	Описание
websiteId	string	Идентификатор сайта на котором установлен чат.
visitorId	string	ID посетителя. Необязательный параметр, используется например, если посетитель авторизовался на сайте с нового устройства. Если передать этот параметр, то для посетителя по его идентификатору будут загружены все его старые данные, включая историю сообщений.

Свойства

Свойство	Тип	Описание
onConnected	`function(visitor: Visitor, newVisitorId: string){}`	Свойству может быть назначена функция обратного вызова, которая будет вызвана после успешного подключения методом `start()`. Если по каким то причинам посетитель не смог подключиться со своим старым идентификатором, то chatix назначит ему новый - `newVisitorId`
onReceivedWebsiteMessage	`function(message: Message){}`	Свойству может быть назначена функция обратного вызова, которая будет вызываться при получении нового сообщения от консультантов чата.
onManagerConnected	`function(manager: Manager) {}`	Свойству может быть назначена функция обратного вызова, которая будет вызываться после подключения консультанта к разговору. В разговоре с посетителем может быть одновременно несколько консультантов.
onManagerDisonnected	`function(manager: Manager) {}`	Свойству может быть назначена функция обратного вызова, которая будет вызываться после отключения консультанта от разговора. В разговоре с посетителем может быть одновременно несколько консультантов.
onRequestScreenCast	`function(){}`	Свойству может быть назначена функция обратного вызова, вызываемая при получении от консультанта запрос на просмотр экрана. При получении такого запроса вам стоит показать информационный блок посетителю с вопросом, согласен ли он включить демонстрацию экрана консультанту. После получения ответа от посетителя вам необходимо вызвать метод `allowScreenCast(answer: boolean)`
onDisconnectManagerFromScreenCast	`function(){}`	Свойству может быть назначена функция обратного вызова, вызываемая при отключении менеджера от просмотра экрана. При получении такого запроса вам стоит скрыть информационный блок о ведении трансляции экрана

Методы

start() : void

Этот метод начинает сетевое взаимодействие. Вы можете запустить Chatix при старте приложение, или же по какому-то событию. Метод ничего не возвращает, но по завершению, метод вызывает функцию обратного вызова в свойстве onConnected

getWebChatInfo(): Promise\

Метод получает конфигурацию чата на сайте. Например может быть полезным определение рабочего времени консультантов с помощью свойства schedule или динамическое управление настройками внешнего вида сообщений. Описание объекта ChatInfo вы можете посмотреть в секции "Используемые классы".

getWebChatManagers(): Promise\<Managers[]>

Метод получает информацию о всех консультантах данного сайта. Может быть полезно чтобы отобразить фотографии, имена и другие данные по вашим консультантам посетителю сайта. Описание объекта Managers можете посмотреть в секции "Используемые классы".

getWebChatConnectedManagers(): Promise\<Managers[]>

Метод получает информацию о всех подключенных в данный момент консультантах данного сайта. Может быть полезно чтобы отобразить фотографии, имена и другие данные по вашим консультантам посетителю сайта. Описание объекта Managers можете посмотреть в секции "Используемые классы".

getVisitor(): Promise\

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

setVisitor(visitor: Visitor)

Аргумент	Тип	Описание
visitor	Visitor	Объект посетителя сайта с обновленными данными.

Метод отправляет в Chatix обновленные сведения о посетителе сайта. Например, после авторизации посетителя на сайте, вы знаете его имя, email и какую-то другую полезную информацию. Для того чтобы консультанты сайта могли понимать с кем они разговаривают и смогли предоставить клиенту более высокий уровень сервиса.

getWebsiteMessages(lastMessageId: string = null, count: int = 30): Promise\<Message[]>

Аргумент	Тип	Описание
lastMessageId	string	Идентификатор последнего известного сообщения в беседе с консультантом. При передаче `NULL` вернет наиболее актуальные сообщения.
count	int	Количество сообщений для возврата.

Метод отдает массив сообщений Message из чата с консультантом. Все сообщения в переписке с консультантом хранятся в хронологическом порядке и отдаются пачками. Количество сообщений в пачке регулируется аргументом count. Для получения последних сообщений из переписки с консультантами, параметр lastMessageId должен содержать NULL. Для загрузки очередной пачки сообщений (например при прокручивании блока сообщений), вам необходимо определить наиболее старое сообщение, отображаемое в данный момент на экране и передать его идентификатор в параметре lastMessageId. SDK определит какие сообщения будут входить в следующую пачку и сформирует для вас ответ. Если в ответе приходит пустой массив, значит вы достигли начала переписки, больше сообщений для отображения нет.

visitorType(text: string = null): void

Аргумент	Тип	Описание
text	string	Текущий набранный текст в блоке ввода сообщения. `NULL` следует отправить если посетитель стер все символы из поля без отправки сообщения. В случае отправки сообщения вызывать этот метод с `NULL` необязательно.

Chatix позволяет консультантам видеть какой текст набирает посетитель сайта. Эта функция позволяет быстрее формулировать ответ и помогать посетителям сайта более эффективно. Используйте этот метод чтобы сообщить консультанту содержимое поля для ввода сообщения еще до непосредственной отправки этого сообщения. Одна из возможностей это сделать - подписаться на событие изменения содержимого поля для ввода сообщения.

sendWebsiteFileMessage(file: File): void

Аргумент	Тип	Описание
file	File	Файл, который вы планируете отправить в чат. Если файл будет указывать на картинку, то Chatix автоматически создаст для него уменьшенные картинки для предпросмотра. Остальные файлы будут отправлены без обработки. Как получить file https://developer.mozilla.org/ru/docs/web/api/file

Метод отправляет файл в диалог с консультантом.

sendWebsiteTextMessage(text: string): void

Аргумент	Тип	Описание
text	string	Текст сообщения.

Метод отправляет текстовое сообщение в диалог с консультантом.

allowScreenCast(answer: boolean): void

Аргумент	Тип	Описание
answer	boolean	Решение посетителя о разрешении просмотра экрана. `TRUE` - посетитель разрешил просмотр своего экрана, `FALSE` - посетитель запретил просмотр своего экрана

Chatix позволяет консультанту просматривать экран посетителя. Для начала просмотра экрана, посетитель должен получить запрос на разрешение просмотра экрана и решить, будет он показывать содержимое или нет. Данный метод отправляет в Chatix полученное решение посетителя. Если вы хотите скрыть какой то элемент от показа менеджеру, то необходимо добавить ему класс ym-disable-keys. Элементы с этим классом не отображаются у менеджера во время просмотра.

interruptScreenCast(): void

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

Вспомогательные классы

Visitor

Visitor - объект представляет данные о текущем посетителе сайта.

Свойство	Тип	Описание
uuid	string (read-only)	Уникальный идентификатор посетителя в Chatix. Например: `6ea5d198-762a-11e9-8f9e-2a86e4085a59`. Не изменяйте значение этого свойства.
name	string	Отображаемое имя посетителя. Может быть его ник, ФИО или другая информация, по которой можно обращаться к вашему посетителю.
email	string	Адрес электронной почты. Например: `demo@example.com`
fields	object	Пользовательские поля посетителя. Каждый сайт и приложение имеет свой особый набор полей, которые он хочет установить посетителю. Это могут быть: внутренний идентификатор, состояние баланса, содержимое корзины и многое другое. Свойство представляет собой обычный объект с полями и значениями. Мы рекомендуем обращаться к данным в этом объекте в виде ассоциативного массива `fields["Property name"]` чтобы получить возможность использовать осмысленные фразы в качестве ключа поля.
avatar_preview	string	Превью аватара посетителя
avatar	string	Аватар посетителя в оригинальном размере
browser_language	string	Язык браузера посетителя. Используется для определения языка виджета по умолчанию
city	string	Город посетителя
country	string	Страна посетителя
current_page_title	string	Заголовок текущейстраницы посетителя
current_url	string	url адрес текущей страницы посетителя
ip	string	ip посетителя
is_screen_cast_allowed	boolean	Отметка давал ли посетитель разрешение на просмотр экрана
online_time	int	Время онлайна посетителя в чате
last_activity	int	Время последней активности посетителя
is_online	boolean	Онлайн ли посетитель в данный момент
time_zone_offset	int	Смещение часового пояса
utm_campaign	string	UTM метка по которой посетитель попал на сайт
utm_content	string	UTM метка по которой посетитель попал на сайт
utm_medium	string	UTM метка по которой посетитель попал на сайт
utm_source	string	UTM метка по которой посетитель попал на сайт
utm_term	string	UTM метка по которой посетитель попал на сайт

Manager

Manager - объект представляет данные о менеджере.

Свойство	Тип	Описание
uuid	string (read-only)	Уникальный идентификатор менеджера в Chatix.
name	string	Имя менеджера.
email	string	Адрес электронной почты.
status	boolean	Показывает подключен ли менеджер к диалогу
isOnline	bool	В сети мнеджер в данный момент или нет.
avatar_thumb100_url	string	Превью аватара менеджера размером 100x100px.
avatar_thumb300_url	string	Превью аватара менеджера размером 300x300px.
avatar_url	string	Аватар менеджера в оригинальном размере.

Message

Message - экземпляры данного класса предоставляют информацию о сообщении в чате. В Chatix существует 3 разных вида сообщений: текстовое сообщение, сообщение с файлом и сообщение с картинкой. Комбинации вроде "сообщение с текстом и файлом одновременно" в Chatix не поддерживаются, такие комбинации должны быть разделены на разные сообщения, но вы можете создать подобный эффект визуальными средствами..

Свойство	Тип	Описание
uuid	string (read-only)	Идентификатор сообщения.
type	int	Тип сообщения, 0 - текстовое, 4 - картинка, 5 - файл
sender_flag	int	Флаг направления сообщения. 0 - сообщение посетителя, 1 - сообщение консультанта
sender_id	string	Идентификатор отправителя. Либо идентификатор посетителя, либо идентификатор консультанта, в зависимости от `sender_flag`.
content	string	Контент сообщения. Формат содержимого зависит от типа сообщения (поле `type`). Для текстовых сообщений (`type == 0`) - простая строка содежимого. Для сообщений с изображением или файлом (`type == 4 или type == 5`) - строка содержит ссылку на файл.

ChatInfo

ChatInfo - экземпляр данного класса предоставляет подробную информацию о чате.

Свойство	Тип	Описание
domains	string[]	Массив с доменами на которых подключен чат
front_template	int	Шаблон виджета по умолчанию
id	string	Идентификатор виджета
members	array	Массив с идентификаторами менеджеров в данном диалоге
offline_greeting_text	string	Встречающее сообщение, показываемое автоматически в нерабочее время
online_greeting_text	string	Встречающее сообщение, показываемое автоматически в рабочее время
organisation_name	string	Название чата
schedule	schedule ScheduleItem7	Расписание работы виджета. Используется для отображения рабочего времени и показа встречающего сообщения. `Воскресенье - 0, Суббота - 6`
style	object	Объект со всеми стилями чата. `background_color: "#94f9d1" – цвет фона виджета` `background_image: "null" – фоновое изображениеbackground_type: 0 - тип фона. 0 – цвет, 1 - изображениеcorner_radius: [20, 20, 20, 20] – радиус скругления углов виджетаheader_color: "#1e777c" – цвет шапки виджетаheader_image: "null" – фоновое изображения шапки виджетаheader_type: 0 - тип фона. 0 – цвет, 1 - изображениеheight: 300 – высота виджетаwidth: 507 – ширина виджетаmanager_message_bg_color: "#237d7f" – цвет входящих сообщенийmanager_message_outline_color: "#ffffff" – цвет обводки входящих сообщенийmanager_message_outline_width: 3 – толщина обводки входящих сообщенийmanager_message_text_color: "#ffffff" - – цвет текста входящих сообщенийsend_button_style: 0 – вид кнопки отправки сообщенийvisitor_message_bg_color: "#1c8094" – цвет исходящих сообщенийvisitor_message_outline_color: "#ffffff" – цвет обводки исходящих сообщенийvisitor_message_outline_width: 3 – толщина обводки исходящих сообщенийvisitor_message_text_color: "#ffffff" – цвет текста исходящих сообщенийtime_zone_utc_offset: 7 – смещение часового пояса менеджера. Используется для синхронизации времени менеджеров и посетителя.`

Schedule

Schedule - массив с расписанием рабочего времени чата. При формировании режима работы важно учитывать часовой пояс, т.к. время у менеджера и посетителя может отличаться. Для этого в объекте ChatInfo есть поле time_zone_utc_offset.

Свойство	Тип	Описание
is_work	boolean	Рабочий\не рабочий день
start	int	Час начала рабочего дня
end	int	Час окончания рабочего дня