> For the complete documentation index, see [llms.txt](https://docs.fstrk.io/knowledge_base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fstrk.io/knowledge_base/channels/web/api.md).

# 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` чтобы виджет не перекрывал важные элементы

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

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