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 - главный объект. Все должно быть сделано с использованием этого объекта. У вас есть доступ к его свойствам и методам, чтобы разработать собственный интерфейс.
Свойства
| Свойство | Тип | Описание |
|---|---|---|
| onConnected | function(){} |
Свойству может быть назначена функция обратного вызова, которая будет вызвана после успешного подключения методом start(). Если по каким то причинам посетитель не смог подключиться со своим старым идентификатором, то chatix назначит ему новый - newVisitorId |
| onConversationMessageReceived | function(message: Message){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться при получении нового сообщения от консультантов чата. |
| onConversationMessageUpdated | function(message: Message){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться при редактировании сообщения консультантом. |
| onConversationMessageDeleted | function(messageId: string){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться при удалении сообщения консультантом. |
| onManagerConnectedToConversation | function(manager: Manager) {} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после подключения консультанта к разговору. В разговоре с посетителем может быть одновременно несколько консультантов. |
| onManagerDisconnectedFromConversation | function(manager: Manager) {} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после отключения консультанта от разговора. В разговоре с посетителем может быть одновременно несколько консультантов. |
| onScreencastPermissionRequested | function(){} |
Свойству может быть назначена функция обратного вызова, вызываемая при получении от консультанта запрос на просмотр экрана. При получении такого запроса вам стоит показать информационный блок посетителю с вопросом, согласен ли он включить демонстрацию экрана консультанту. После получения ответа от посетителя вам необходимо вызвать метод allowScreenCast(answer: boolean) |
| onManagerConnectToScreenCast | function(){} |
Свойству может быть назначена функция обратного вызова, вызываемая при подключении менеджера к просмотра экрана. |
| onManagerDisconnectFromScreenCast | function(){} |
Свойству может быть назначена функция обратного вызова, вызываемая при отключении менеджера от просмотра экрана. При получении такого запроса вам стоит скрыть информационный блок о ведении трансляции экрана |
| onChatroomMessageReceived | function(chatroomId: string, message: Message){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться при получении нового сообщения в чат-комнате. |
| onChatroomMessageUpdated | function(message: Message){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться при редактировании сообщения в чат-комнате консультантом. |
| onChatroomMessageDeleted | function(messageId: string){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться при удалении сообщения в чат-комнате консультантом. |
| onManagerConnectedToChatroom | function(chatroomId: string, manager: Manager){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после подключения менеджера к чат-комнате. |
| onVisitorConnectToChatroom | function(chatroomId: string, visitor: Visitor){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после подключения нового участника к чат-комнате. |
| onManagerDisconnectedFromChatroom | function(chatroomId: string, manager: Manager){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после отключения менеджера от чат-комнаты. |
| onVisitorDisconnectFromChatroom | function(chatroomId: string, visitor: Visitor){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после отключения участника от чат-комнаты. |
| onChatroomCreated | function(chatroom: Chatroom){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после создания новой чат-комнаты. |
| onChatroomUpdated | function(chatroom: Сhatroom){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после изменения чат-комнаты. |
| onChatroomDeleted | function(chatroomId: string){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после удаления чат-комнаты. |
| onChatroomRestored | function(chatroom: Сhatroom){} |
Свойству может быть назначена функция обратного вызова, которая будет вызываться после восстановления удаленной чат-комнаты. |
Методы
start() : Promise<Boolean>
Этот метод начинает сетевое взаимодействие. Вы можете запустить Chatix при старте приложение, или же по какому-то событию. Метод ничего не возвращает, но по завершению, метод вызывает функцию обратного вызова в свойстве onConnected
getWebChat(): Promise<ChatInfo>
Метод получает конфигурацию чата на сайте. Например может быть полезным определение рабочего времени консультантов с помощью свойства ScheduleItem или динамическое управление настройками внешнего вида сообщений. Описание объекта ChatInfo вы можете посмотреть в секции "Используемые классы".
getAllManagers(): Promise<Managers[]>
Метод получает информацию о всех консультантах данного сайта. Может быть полезно чтобы отобразить фотографии, имена и другие данные по вашим консультантам посетителю сайта. Описание объекта Managers можете посмотреть в секции "Используемые классы".
getConnectedManagers(): Promise<Managers[]>
Метод получает информацию о всех подключенных в данный момент консультантах данного сайта. Может быть полезно чтобы отобразить фотографии, имена и другие данные по вашим консультантам посетителю сайта. Описание объекта Managers можете посмотреть в секции "Используемые классы".
getVisitor(): Promise<Visitor>
Метод отдает информацию о посетителе. Можете использовать для отображения фото, имени или другой информации о текущем посетителе в чате.
setVisitor(visitor: Visitor): Promise
| Аргумент | Тип | Описание |
|---|---|---|
| visitor | Visitor | Объект посетителя сайта с обновленными данными. |
Метод отправляет в Chatix обновленные сведения о посетителе сайта. Например, после авторизации посетителя на сайте, вы знаете его имя, email и какую-то другую полезную информацию. Для того чтобы консультанты сайта могли понимать с кем они разговаривают и смогли предоставить клиенту более высокий уровень сервиса.
getConversationMessages(lastMessageId: string = null, count: int = 30): Promise<Message[]>
| Аргумент | Тип | Описание |
|---|---|---|
| lastMessageId | string | Идентификатор последнего известного сообщения в беседе с консультантом. При передаче NULL вернет наиболее актуальные сообщения. |
| count | int | Количество сообщений для возврата. |
Метод отдает массив сообщений Message из чата с консультантом. Все сообщения в переписке с консультантом хранятся в хронологическом порядке и отдаются пачками. Количество сообщений в пачке регулируется аргументом count. Для получения последних сообщений из переписки с консультантами, параметр lastMessageId должен содержать NULL. Для загрузки очередной пачки сообщений (например при прокручивании блока сообщений), вам необходимо определить наиболее старое сообщение, отображаемое в данный момент на экране и передать его идентификатор в параметре lastMessageId. SDK определит какие сообщения будут входить в следующую пачку и сформирует для вас ответ. Если в ответе приходит пустой массив, значит вы достигли начала переписки, больше сообщений для отображения нет.
visitorType(text: string = ''): void
| Аргумент | Тип | Описание |
|---|---|---|
| text | string | Текущий набранный текст в блоке ввода сообщения. NULL следует отправить если посетитель стер все символы из поля без отправки сообщения. В случае отправки сообщения вызывать этот метод с NULL необязательно. |
Chatix позволяет консультантам видеть какой текст набирает посетитель сайта. Эта функция позволяет быстрее формулировать ответ и помогать посетителям сайта более эффективно. Используйте этот метод чтобы сообщить консультанту содержимое поля для ввода сообщения еще до непосредственной отправки этого сообщения. Одна из возможностей это сделать - подписаться на событие изменения содержимого поля для ввода сообщения.
sendConversationTextMessage(text: string): void
| Аргумент | Тип | Описание |
|---|---|---|
| text | string | Текст сообщения. |
Метод отправляет текстовое сообщение в диалог с консультантом.
sendConversationFileMessage(file: File): void
| Аргумент | Тип | Описание |
|---|---|---|
| file | File | Файл, который вы планируете отправить в чат. Если файл будет указывать на картинку, то Chatix автоматически создаст для него уменьшенные картинки для предпросмотра. Остальные файлы будут отправлены без обработки. Как получить file https://developer.mozilla.org/ru/docs/web/api/file |
Метод отправляет файл в диалог с консультантом.
sendScreencastPermission(answer: boolean): void
| Аргумент | Тип | Описание |
|---|---|---|
| answer | boolean | Решение посетителя о разрешении просмотра экрана. TRUE - посетитель разрешил просмотр своего экрана, FALSE - посетитель запретил просмотр своего экрана |
Chatix позволяет консультанту просматривать экран посетителя. Для начала просмотра экрана, посетитель должен получить запрос на разрешение просмотра экрана и решить, будет он показывать содержимое или нет. Данный метод отправляет в Chatix полученное решение посетителя. Если вы хотите скрыть какой то элемент от показа менеджеру, то необходимо добавить ему класс ym-disable-keys. Элементы с этим классом не отображаются у менеджера во время просмотра.
interruptScreenCast(): void
С помощью этого метода посетитель может прервать транслцию экрана в любой момент.
connectToChatroom(chatroomId: string): void
| Аргумент | Тип | Описание |
|---|---|---|
| chatroomId | string | Идентификатор чат-комнаты к которой необходимо подключиться. |
Метод подключает посетителя к чат-комнате.
disconnectFromChatroom(chatroomId: string): void
| Аргумент | Тип | Описание |
|---|---|---|
| chatroomId | string | Идентификатор чат-комнаты. |
Метод отключает посетителя от чат-комнаты.
sendChatroomTextMessage(chatroomId: string, text: string): void
| Аргумент | Тип | Описание |
|---|---|---|
| chatroomId | string | Идентификатор чат-комнаты в которое отправляется сообщение. |
| text | string | Текст сообщения. |
Метод отправляет текстовое сообщение в чат-комнате.
sendChatroomFileMessage(chatroomId: string, file: File): void
| Аргумент | Тип | Описание |
|---|---|---|
| chatroomId | string | Идентификатор чат-комнаты. |
| file | File | Файл, который вы планируете отправить в чат. Если файл будет указывать на картинку, то Chatix автоматически создаст для него уменьшенные картинки для предпросмотра. Остальные файлы будут отправлены без обработки. Как получить file https://developer.mozilla.org/ru/docs/web/api/file |
Метод отправляет сообщение с файлом в чат-комнату.
getChatroomMessages(chatroomId: string, lastMessageId: string = null, count: int = 30): Promise<Messages[]>
| Аргумент | Тип | Описание |
|---|---|---|
| chatroomId | string | Идентификатор чат-комнаты. |
| lastMessageId | string | Идентификатор последнего известного сообщения в беседе с консультантом. При передаче NULL вернет наиболее актуальные сообщения. |
| count | int | Количество сообщений для возврата. |
Метод возвращает массив сообщений отсортированных по дате и времени
getAllChatrooms(): Promise<Chatrooms>
Метод возвращает массив всех доступных чат-комнат.
getMyChatrooms(): Promise<Chatrooms>
Метод возвращает массив чат-комнат к которым подключен посетитель.
getChatroom(chatroomId: string): Promise<Chatroom>
| Аргумент | Тип | Описание |
|---|---|---|
| chatroomId | string | Идентификатор чат-комнаты. |
Метод возвращает объект чат-рума
getMember(memberId: string): Promise<VisitorInfo>
| Аргумент | Тип | Описание |
|---|---|---|
| visitorId | string | Идентификатор посетителя. |
Метод позволяет посетителю получить информацию о другом посетителе по его идентификатору.
getChatromMembers(chatroomId: string, itemsPerPage: int, numberOfPage: int): Promise<Visitor>
| Аргумент | Тип | Описание |
|---|---|---|
| chatroomId | string | Идентификатор чат-комнаты. |
| itemsPerPage | int | Сколько записей на одной странице. |
| numberOfPage | int | Номер страницы. |
Метод позволяет посетителю получить всех посетителей подключенных к чат-комнате.
getMinutesToWork(): string
Метод возвращает время в минутах до начала рабочего дня менеджера. Или 0, если сегодня выходной.
getIsConnected(): boolean
Метод возвращает текущее состояние подключения к серверу.
Вспомогательные классы
Visitor
Visitor - объект представляет данные о текущем посетителе сайта.
| Свойство | Тип | Описание |
|---|---|---|
| uuid | string (read-only) | Уникальный идентификатор посетителя в Chatix. Например: 6ea5d198-762a-11e9-8f9e-2a86e4085a59. Не изменяйте значение этого свойства. |
| name | string | Отображаемое имя посетителя. Может быть его ник, ФИО или другая информация, по которой можно обращаться к вашему посетителю. |
| 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 метка по которой посетитель попал на сайт |
VisitorInfo
VisitorInfo - объект представляет данные о запрошенном посетителе.
| Свойство | Тип | Описание |
|---|---|---|
| uuid | string | Уникальный идентификатор посетителя в Chatix. |
| avatar | string | Оригинал аватара посетителя. |
| avatar_preview | string | Уменьшенный аватар посетителя. |
| name | string | Имя посетителя. |
Manager
Manager - объект представляет данные о менеджере.
| Свойство | Тип | Описание |
|---|---|---|
| uuid | string (read-only) | Уникальный идентификатор менеджера в Chatix. |
| name | string | Имя менеджера. |
| string | Адрес электронной почты. | |
| is_online | boolean | В сети мнеджер в данный момент или нет. |
| 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 | array ScheduleItem[7] | Расписание работы виджета. Используется для отображения рабочего времени и показа встречающего сообщения. Воскресенье - 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 – смещение часового пояса. Используется для синхронизации времени менеджеров и посетителя. |
ScheduleItem
ScheduleItem - массив с расписанием рабочего времени чата.
| Свойство | Тип | Описание |
|---|---|---|
| is_work | boolean | Рабочий\не рабочий день |
| start | int | Начало рабочего дня |
| end | int | Окончание рабочего дня |
Chatroom
Chatroom - экземпляр данного класса предоставляет подробную информацию о чат-комнате.
| Свойство | Тип | Описание |
|---|---|---|
| id | string | Идентификатор чат-комнаты |
| is_deleted | boolean | Отметка удалена чат-комната или нет |
| is_private | boolean | Приватная чат-комната или нет |
| managers | array | Массив со всеми меннеджерами в данной чат-комнате |
| title | string | Название чат комнаты |
| number_of_visitors | int | Количество посетителей в данной чат-комнате |
| web_chat_id | string | Идентификатор веб чата |