# Реализация ботов на основе API

Помимо использования универсального AI-помощника в Telegram ({tg}`giga_education_bot`) у Вас есть возможность самостоятельно реализовать интерфейс взаимодействия с пользователем и осуществлять запросы через API к интеллектуальному ядру AI-помощника.

## Платформы, которые могут использоваться для подключения
- Мессенджеры/социальные сети (Telegram, Discord, VK и т.д.)
- Web-сайты (например, на официальных сайтах вуза/факультета через специальные формы)

## Получение API-Токена
Для получения токена или иным вопросам технического характера вы можете обратиться через представителя в Telegram-бот технической поддержки: {tg}`giga_education_support_bot`

## Получение ответа на вопрос: POST /answer
### Параметры запроса 

| Параметр        | Формат | Описание                                                               | Пример                          |
|-----------------|--------|------------------------------------------------------------------------|---------------------------------|
| **university**  | str    | Идентификатор университета                                             | `"spbu"`, `"itmo"`              |
| **current_question** | str | Вопрос пользователя                                                    | `"Сколько мест на программе…"`   |
| **dialog_style** | str   | Стиль диалога                                                          | `“standart”, “slang”, “pedantic”` |
| **chat_id**     | str    | Уникальный ID чата/пользователя                                        | `"1400023"`                     |
| **message_id**  | str    | ID сообщения пользователя                                              | `"8800012"`                     |
| **msg_datetime** | str   | Дата и время запроса в формате `yyyy-mm-dd hh:mm:ss`                    | `"2024-04-15 12:10:01"`         |
| **access_token** | str   | Токен для доступа к API                                                | `"token"`                       |

- _Если платформа, на базе которой вы хотите использовать API AI-помощника, не предоставляет информацию о пользователе, необходимо самостоятельно реализовать процедуру генерации уникального идентификатора. ID требуется для учета контекста диалога с пользователем, а также для стилизации ответа._
### JSON-ответ

| Параметр       | Формат | Описание                                        | Пример                                     |
|----------------|--------|-------------------------------------------------|--------------------------------------------|
| **final_answer** | str    | Ответ, сгенерированный AI-помощником            | `"Образовательные программы в спбгу?"`    |
| **titles**      | list   | Список с заголовками для релевантных ссылок     | `["title 1", "title 2"]`                   |
| **urls**        | list   | Список с релевантными ссылками                  | `["url 1", "url 2"]`                       |
| **modified_question** | str  | Переформулированный с учетом контекста вопрос пользователя | `"Какие образовательные программы, включая бакалавриат и магистратуру, предлагает Санкт-Петербургский государственный университет?"` |
| **is_ambiguous** | bool  | Требует ли данный вопрос уточнения | `"Когда начинается заселение в общежитие?"` |
- _Параметр *is_ambiguous* указывает, требует ли вопрос уточнения. Если его значение *True*, то titles и urls вернут *None*_ 

### Статусы ответа
- 200 - ok
- 401 - JWT Токен не прошёл аутентификацию


## Удаление истории диалога пользователя: PUT /clean_user_history
### Параметры запроса 

| Параметр (body)        | Формат | Описание                                                               | Пример                          |
|-----------------|--------|------------------------------------------------------------------------|---------------------------------|
| **chat_id**  | str    | Идентификатор университета                                             | `"spbu"`, `"itmo"`              |

- _Если платформа, на базе которой вы хотите использовать API AI-помощника, не предоставляет информацию о пользователе, необходимо самостоятельно реализовать процедуру генерации уникального идентификатора. ID требуется для учета контекста диалога с пользователем, а также для стилизации ответа._

### Статусы ответа
- 200 - ok
- 409 - История пользователя пуста
- 401 - JWT Токен не прошёл аутентификацию


## Получение настроек университета: GET /uni/{uni_id}/info/prod
### Параметры запроса 

| Параметр        | Формат | Описание                                                               | Пример                          |
|-----------------|--------|------------------------------------------------------------------------|---------------------------------|
| **uni_id**  | str    | Идентификатор университета                                             | `"spbu"`, `"itmo"`              |

### JSON-ответ

| **Parameter**            | **Description**                                           | **Example**                                                                                  |
|--------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `website`                | Ссылка на официальную страницу ВУЗа                                   | `http://www.klgtu.ru`                                                                        |
| `head_uni`               | Главный ли это домен, для случая с филиалами                                 | True                                                                                       |
| `uni_name`               | Наименование университета (аббревиатура)                                  | `КГТУ`                                                                                       |
| `introduction`           | Темы, на которые имеются данные                                 | `Я могу рассказать об образовательных программах, сроках приема, общих сведениях...`          |



### Статусы ответа
- 200 - ok
- 403 - Доступ запрещён
- 401 - JWT Токен не прошёл аутентификацию


## Шаблонный Телеграм-Бот
Для ускорения процедуры разработки мы также предлагаем воспользоваться [готовым решением](https://github.com/GigaUniversity/ai_assistant_template_tg_bot).  
В документации к репозиторию (README.md) содержится инструкция по запуску.  
Для получения **ACCESS_TOKEN** необходимо обратиться в Telegram-бота поддержки проекта.
Минимальные требуемые ресурсы для развёртывания:
* RAM: 256 MB
* CPU: Any
* ROM: 512 MB  

_В шаблоне используется лишь один образ: сам Телеграм-бот. При желании, вы можете добавить Redis, чтобы хранить кэш не в оперативной памяти, а также Базу Данных (например, PostgreSQL) для хранения информации о пользователях. В таком случае *RAM повысится до 512 MB*_