![Логотип Chatix](https://static.tildacdn.com/tild6361-6335-4134-a465-363339336564/chatix_logo256.png) # Chatix Core Chatix Core - JS SDK которое позволяет создавать встроенные в ваше web-приложение чаты и использовать платформу Chatix как поставщика серверной части. Chatix занимается обслуживанием сетевого соединения и хранением данных, а вам остается только отобразить эти данные вашему пользователю. ## Первые шаги Прежде всего вам нужен аккаунт Chatix, чтобы вы смогли использовать этот SDK на своем сайте. Посетите сайт [chatix.io](https://chatix.io "chatix.io") чтобы создать бесплатный аккаунт и получиить свой `website_id`. Этот идентификатор определяет ваш сайт в Chatix и это обязтельный атрибут для конструктора SDK. Когда вы получите свой `website_id`, вы сможете приступить к разработке чатов с Chatix Core. ## Установка 1. Установите пакет [chatix-core](https://www.npmjs.com/package/chatix-core) с помощью своего пакетного менеджера 2. Импортируйте ChatixCore в свое приложение `import ChatixCore from 'chatix-core'`. **Важно: В приложении должна быть только одна сущность SDK.** 3. Создайте экземпляр ChatixCore и передайте в конструктор свой идентификатор `let core = new ChatixCore(websiteId);`. Подробная документация по свойствам и методам SDK будет рассказана ниже. 4. Начните соединение вызовом `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\ Этот метод начинает сетевое взаимодействие. Вы можете запустить Chatix при старте приложение, или же по какому-то событию. Метод ничего не возвращает, но по завершению, метод вызывает функцию обратного вызова в свойстве `onConnected` #### getWebChat(): Promise\ Метод получает конфигурацию чата на сайте. Например может быть полезным определение рабочего времени консультантов с помощью свойства `ScheduleItem` или динамическое управление настройками внешнего вида сообщений. Описание объекта [ChatInfo](###ChatInfo) вы можете посмотреть в секции "Используемые классы". #### getAllManagers(): Promise\ Метод получает информацию о всех консультантах данного сайта. Может быть полезно чтобы отобразить фотографии, имена и другие данные по вашим консультантам посетителю сайта. Описание объекта [Managers](###Manager) можете посмотреть в секции "Используемые классы". #### getConnectedManagers(): Promise\ Метод получает информацию о всех подключенных в данный момент консультантах данного сайта. Может быть полезно чтобы отобразить фотографии, имена и другие данные по вашим консультантам посетителю сайта. Описание объекта [Managers](###Manager) можете посмотреть в секции "Используемые классы". #### getVisitor(): Promise\ Метод отдает информацию о посетителе. Можете использовать для отображения фото, имени или другой информации о текущем посетителе в чате. #### setVisitor(visitor: Visitor): Promise | Аргумент | Тип | Описание | | --- | --- | --- | | visitor | [Visitor](###Visitor) | Объект посетителя сайта с обновленными данными. | Метод отправляет в Chatix обновленные сведения о посетителе сайта. Например, после авторизации посетителя на сайте, вы знаете его имя, email и какую-то другую полезную информацию. Для того чтобы консультанты сайта могли понимать с кем они разговаривают и смогли предоставить клиенту более высокий уровень сервиса. #### getConversationMessages(lastMessageId: string = null, count: int = 30): Promise\ | Аргумент | Тип | Описание | | --- | --- | --- | | lastMessageId | string | Идентификатор последнего известного сообщения в беседе с консультантом. При передаче `NULL` вернет наиболее актуальные сообщения. | | count | int | Количество сообщений для возврата. | Метод отдает массив сообщений [Message](###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\ | Аргумент | Тип | Описание | | --- | --- | --- | | chatroomId | string | Идентификатор чат-комнаты. | | lastMessageId | string | Идентификатор последнего известного сообщения в беседе с консультантом. При передаче `NULL` вернет наиболее актуальные сообщения. | | count | int | Количество сообщений для возврата. | Метод возвращает массив сообщений отсортированных по дате и времени #### getAllChatrooms(): Promise\ Метод возвращает массив всех доступных чат-комнат. #### getMyChatrooms(): Promise\ Метод возвращает массив чат-комнат к которым подключен посетитель. #### getChatroom(chatroomId: string): Promise\ | Аргумент | Тип | Описание | | --- | --- | --- | | chatroomId | string | Идентификатор чат-комнаты. | Метод возвращает объект чат-рума #### getMember(memberId: string): Promise\ | Аргумент | Тип | Описание | | --- | --- | --- | | visitorId | string | Идентификатор посетителя. | Метод позволяет посетителю получить информацию о другом посетителе по его идентификатору. #### getChatromMembers(chatroomId: string, itemsPerPage: int, numberOfPage: int): Promise\ | Аргумент | Тип | Описание | | --- | --- | --- | | 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 | Отображаемое имя посетителя. Может быть его ник, ФИО или другая информация, по которой можно обращаться к вашему посетителю. | | 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 метка по которой посетитель попал на сайт | ### VisitorInfo **VisitorInfo** - объект представляет данные о запрошенном посетителе. | Свойство | Тип | Описание | | ------------ | ------------ | ------------ | | uuid | string | Уникальный идентификатор посетителя в Chatix. | | avatar | string | Оригинал аватара посетителя. | | avatar_preview | string | Уменьшенный аватар посетителя. | | name | string | Имя посетителя. | ### Manager **Manager** - объект представляет данные о менеджере. | Свойство | Тип | Описание | | ------------ | ------------ | ------------ | | uuid | string *(read-only)* | Уникальный идентификатор менеджера в Chatix. | | name | string | Имя менеджера. | | email | 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 | Идентификатор веб чата |