# Оглавление
- [Интеграция](#integraciya)
- [ServiceId](#serviceid)
- [Открытие чатов закрытого контура](#otkrytie-chatov-zakrytogo-kontura)
- [Открытие конкретного чата](#otkrytie-konkretnogo-chata)
- [Использование флагов для настройки Мессенджера](#ispolzovanie-flagov-dlya-nastrojki-messendzhera)
- [Событие скрытия/открытия виджета](#sobytie-skrytiya/otkrytiya-vidzheta)
- [Перехват открытия информации о пользователе/чате](#perehvat-otkrytiya-informacii-o-polzovatele/chate)
- [Доступ к счетчику непрочитанных сообщений](#dostup-k-schetchiku-neprochitannyh-soobshenij)
- [UI](#ui)
- [Цветовые темы](#temy)
- [React](#react)
- [Содержание документации](#soderzanie-documentacii)

## Интеграция

1. Зарегистрировать интеграцию

    Для этого обратитесь в поддержку Мессенджера - заполните [форму](https://yandex.ru/support/messenger/feedback.html). В ответном письме вы получите `serviceId`, который необходимо передать в виджет.

2. Поддержать OAuth авторизацию

    Мессенджеру для авторизации необходим OAuth-токен, выписанный на OAuth-приложение со скоупом Яндекс.Ямб. Токен нужно передать в виджет.
    ```ts
    const widget = createMultiChatsWidget({
        serviceId: SERVICE_ID,
        authToken: `OAuth ${token}`,
        ...
    });
    ```
    Завести OAuth-приложение и получить токен можно через Яндекс ID ([Документация](https://yandex.ru/dev/id/doc/ru/concepts/ya-oauth-intro)).
    Для этого нужно заполнить форму заведения нового приложения ([форма](https://oauth.yandex.ru/client/new)). В этой форме в поле "Доступ к данным" (scope авторизации) нужно выбрать *Яндекс.Ямб (Чтение и отправка сообщений в чатах)*.



3. Интегрировать [виджет](./widget.md)

###### **О локальной разработке:**
* До выдачи `serviceId` можно использовать **localhost** домены.
* Всегда используйте **https**.
* Используйте `serviceId = -1`.

## ServiceId

`ServiceId` является обязательным параметром для интеграции. Как его завести, смотрите в разделе [про интеграцию](#integraciya).

## Открытие чатов закрытого контура

Чтобы открыть в виджете чаты только вашей организации, нужно передать id организации в фабрику виджета:

```ts
const widget = createMultiChatsWidget({
    serviceId: SERVICE_ID,
    orgId: ORGANIZATION_ID,
});
```

## Открытие конкретного чата
Для открытия конкретного чата предусмотрено два механизма:

* Чат по умолчанию. Настроить его можно через параметр `iframeOpenData` в конфиге виджета.
Подходит для случаев, когда у вас 1 чат, и вы хотите, чтобы он открывался при клике на кнопку виджета или при вызове `Widget::show` без параметров.

* Открытие чата с помощью метода `Widget::show`. В данном случае вам необходимо передать в метод параметры открытия чата. Подходит для случаев, когда вы используете свою кнопку открытия виджета.


Для открытия чата можно использовать **один** из идентификаторв чата: `chatId`, `guid`, `inviteHash`, `alias`, `deeplink`. Крайне не рекомендуется передавать несколько идентификаторов одновременно. Подробнее с идентификаторами чатов можно ознакомиться [здесь](./interfaces.md#iframeopenparams).



Если необходимо динамически изменить контекст чата, можно использовать метод `Widget:show` повторно.



## Использование флагов для настройки Мессенджера

С помощью [флагов](./flags.md) можно настраивать отображение и поведение Мессенджера.

## Событие скрытия/открытия виджета

Для определения текущего состояния виджета в `PopupUI` и `ButtonUI` доступны событие `onToggled` и свойство `hidden`.

## Перехват открытия информации о пользователе/чате

Виджет позволяет перехватить открытие стандартного интерфейса информации о пользователе/чате и выполнить вместо этого сценарий сервиса.

Для этого нужно:
1. Установить [флаг](./flags.md) `uiInterceptors` с нужным вам значением.
2. Обработать [вызов метода](./handlers.md) `uiInterceptor`.

## Доступ к счетчику непрочитанных сообщений

Если интегрирован виджет с кнопкой или попап, используйте события и методы [UnreadCounterPlugin](./plugin-unread-counter.md).

Если интегрирован block ui, используйте [событие](./events.md) `counter`.

## UI

Предоставляется три готовых варианта UI виджета, также можно написать свой:

* [Виджет для инлайн вставки](./ui-block.md);

* [Виджет-попап](./ui-popup.md);

* [Виджет-попап с кнопкой](./ui-button.md).

## Цветовые темы
Включить одну из предустановленных тем Мессенджера можно через флаг `theme`.
Отдельные цвета Мессенджера можно переоределить с помощью параметра `themeVariables` объекта Options, передаваемого в функции-фабрики. [Подробнее](./themes).

Флаг `theme` не влияет на тему **виджета**, ее необходимо настроить самостоятельно с помощью CSS-переменных, описанных в документации по каждому UI.

Если необходимо изменить цветую схему Мессенджера в рантайме, нужно использовать метод `setThemeVariables` [api](./api).


## React

[Пример интеграции виджета в React приложение](./react.md)

## Содержание документации

- [API виджета](./api.md)
- [События виджета](./events.md)
- [Флаги, позволяющие настроить **Мессенджер**](./flags.md)
- [Обработчики запросов Мессенджера (События Мессенджера)](./handlers.md)
- [Все типы пакета](./interfaces.md)
- [Плагин, открывающий виджет по кликам на диплинки](./plugin-deep-linker.md)
- [Плагин, добавляющий счетчик непрочитанных к ui](./plugin-unread-counter.md)
- [Плагин, позволяющий повесить обработчик на ошибку авторизации](./plugin-handle-critical-error.md)
- [Пример интеграции в React приложение](./react.md)
- [Про темы Мессенджера](./themes.md)
- [Картинка с цветами тем](./themes-colors.png)
- [UI Block](./ui-block.md)
- [UI Button](./ui-button.md)
- [UI Popup](./ui-popup.md)
- [Класс виджета](./widget.md)
- [Функции-фабрики для создания виджета](./widgetCreators.md)