# API для виджета Fasttrack

Описанное API предоставляет контроль над настройками, поведением и взаимодействием с виджетом Fasttrack.

### Быстрый старт

```javascript
// Базовая настройка
window.fasttrack = {
  autoStart: true,
  context: {
    name: "{{name}}",
    phone: "{{phone}}",
    email: "{{email}}"
  },
  settings: {
    // настройки виджета
  }
};

// Инициализация
window.fasttrack.init('uuid виджета');
window.fasttrack.connect();
```

### Конфигурация

#### Основные параметры

**`autoStart`**

* **Тип:** `boolean`
* **Описание:** Автоматический запуск виджета при загрузке страницы
* **По умолчанию:** `true`

**`context`**

* **Тип:** `object`
* **Описание:** Набор переменных контекста для передачи дополнительных данных
* **Пример:**

```javascript
window.fasttrack = {
  context: {
    name: "{{name}}",
    phone: "{{phone}}",
    email: "{{email}}"
  },
  // ...
};
```

#### Настройки виджета (`settings`)

**Настройки обложки**

```javascript
cover: {
  title: "Fasttrack",              // Заголовок в шапке
  subTitle: "Чат-боты для бизнеса" // Дополнительный текст в шапке
}
```

**Порядок блоков**

Массив объектов, определяющих порядок и настройки блоков на обложке:

```javascript
coverOrder: [
  {
    app: "HELLO",
    enable: true,
    title: "Добро пожаловать 👋",
    description: "Чем мы можем вам помочь?"
  },
  {
    app: 'CHAT',
    enable: true,
    title: "Написать сообщение",
    description: "Открыть онлайн-чат"
  },
  {
    app: 'PLATFORMS',
    enable: true
  }
]
```

**Доступные типы блоков:**

* `HELLO` - блок приветствия
* `CHAT` - блок с кнопкой онлайн-чата
* `PLATFORMS` - блок с мессенджерами

**Настройки отображения**

```javascript
settings: {
  desktopVisible: 'SHOW',    // Видимость на десктопе: 'SHOW' | 'HIDE'
  mobileVisible: 'HIDE',     // Видимость на мобильных: 'SHOW' | 'HIDE'
  initialMode: 'NONE',       // Начальный режим: 'NONE' | 'BUTTON'
  mainColor: '#228BE6',      // Основной цвет виджета
  side: 'RIGHT',             // Сторона размещения: 'LEFT' | 'RIGHT'
  offsetX: 20,               // Отступ по горизонтали (px)
  offsetY: 20,               // Отступ по вертикали (px)
  zIndex: 5                  // Z-index виджета
}
```

### Методы API

#### Инициализация и управление

**`init(uuid)`**

Инициализирует виджет с указанным UUID.

```javascript
window.fasttrack.init('widget-uuid');
```

**Параметры:**

* `uuid` (string) - уникальный идентификатор виджета

**`connect()`**

Устанавливает соединение с сервером и создает пользователя.

```javascript
window.fasttrack.connect();
```

**`destroy()`**

Отключает и скрывает виджет.

```javascript
window.fasttrack.destroy();
```

#### События жизненного цикла

**`onReady(callback)`**

Вызывается когда виджет загружен и готов к инициализации.

```javascript
window.fasttrack.onReady(() => {
  console.log('Виджет готов к инициализации');
});
```

**`onMount(callback)`**

Вызывается когда виджет готов к работе.

```javascript
window.fasttrack.onMount(() => {
  console.log('Виджет готов к работе');
});
```

#### Управление настройками

**`setSettings(settings)`**

Устанавливает новые настройки виджета.

```javascript
const newSettings = {
  mainColor: '#FF5722',
  side: 'LEFT'
};
window.fasttrack.setSettings(newSettings);
```

**Параметры:**

* `settings` (object) - объект с новыми настройками

#### Отправка сообщений

**`sendMessage(options)`**

Отправляет сообщение в чат.

```javascript
window.fasttrack.sendMessage({
  message: 'Ваше сообщение',
  c: 1,              // ID Диплинка
  n: 1,              // ID Сценария (узла)
  getParams: {}      // Дополнительные параметры (необязательно)
});
```

**Параметры:**

* `message` (string) - текст сообщения
* `c` (number, optional) - ID диплинка
* `n` (number, optional) - ID сценария (узла)
* `getParams` (object, optional) - объект с дополнительными параметрами

#### Управление приглашениями

**`showInvite(uuid, options?)`**

Показывает приглашение пользователю.

```javascript
// Простое приглашение
window.fasttrack.showInvite('invite-uuid');

// Приглашение с переменными
window.fasttrack.showInvite('invite-uuid', {
  vars: { 
    v1: 'name1', 
    v2: 'name2' 
  },
  message: 'Текст вашего сообщения {{v1}}' // необязательно
});
```

**Параметры:**

* `uuid` (string) - UUID приглашения
* `options` (object, optional) - дополнительные опции:
  * `vars` (object) - переменные для подстановки в шаблон
  * `message` (string) - кастомный текст сообщения

#### Управление интерфейсом

**`openCover()`**

Показывает обложку виджета.

```javascript
window.fasttrack.openCover();
```

**`openChat()`**

Открывает окно чата.

```javascript
window.fasttrack.openChat();
```

**`openButton()`**

Показывает кнопку виджета.

```javascript
window.fasttrack.openButton();
```

**`close()`**

Закрывает виджет (показывает только кнопку).

```javascript
window.fasttrack.close();
```

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

#### Базовая интеграция

```javascript
window.fasttrack = {
  autoStart: true,
  context: {
    name: "Иван Иванов",
    phone: "+7 (999) 123-45-67",
    email: "ivan@example.com"
  },
  settings: {
    cover: {
      title: "Поддержка",
      subTitle: "Мы всегда готовы помочь"
    },
    mainColor: '#2196F3',
    side: 'RIGHT',
    desktopVisible: 'SHOW',
    mobileVisible: 'SHOW'
  }
};

window.fasttrack.init('widget-uuid');
window.fasttrack.connect();
```

#### Пример программного управления

```javascript
// Ожидание готовности виджета
window.fasttrack.onReady(() => {
  console.log('Виджет загружен');
  
  // Инициализация
  window.fasttrack.init('widget-uuid');
});

window.fasttrack.onMount(() => {
  console.log('Виджет готов к работе');
  
  // Автоматическое открытие чата через 5 секунд
  setTimeout(() => {
    window.fasttrack.openChat();
  }, 5000);
});
```

#### Отправка сообщений с контекстом

```javascript
// Отправка сообщения с дополнительными параметрами
window.fasttrack.sendMessage({
  message: 'Здравствуйте! У меня вопрос по заказу.',
  c: 1,
  n: 2,
  getParams: {
    orderId: '12345',
    source: 'website',
    page: window.location.pathname
  }
});
```

#### Работа с приглашениями

```javascript
// Показ персонализированного приглашения
window.fasttrack.showInvite('invite-uuid', {
  vars: {
    userName: 'Анна',
    productName: 'Premium подписка.'
  },
  message: 'Привет, {{userName}}! Хотите узнать больше о {{productName}}?'
});
```

### Лучшие практики

1. **Инициализация:** Всегда используйте события `onReady` и `onMount` для корректной инициализации
2. **Контекст:** Передавайте актуальную информацию о пользователе в `context`
3. **Адаптивность:** Настраивайте `desktopVisible` и `mobileVisible` в зависимости от целевой аудитории
4. **Производительность:** Используйте `autoStart: false` если виджет не нужен сразу при загрузке
5. **UX:** Настраивайте `offsetX`, `offsetY` и `zIndex` чтобы виджет не перекрывал важные элементы

### Поддержка

Для получения дополнительной информации и поддержки обратитесь к менеджеру вашего проекта.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fstrk.io/knowledge_base/channels/web/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.