# Про ботів для груп Telegram

ConnectiveOne дозволяє створювати ботів, які можуть слухати та відповідати в групах Telegram. Це дозволяє автоматизувати роботу в групах, обробляти команди та передавати повідомлення операторам.

## Контекст і проблема

У багатьох випадках потрібна автоматизація роботи в групах Telegram:
- Бот, який виконує команди в групах (`/command@mybot`)
- Бот, який розпізнає звернення до себе (`@mybot зверни увагу`)
- Бот, який слухає всі повідомлення в групі та передає їх операторам

Боти для груп вирішують цю задачу, дозволяючи автоматизувати роботу та надавати операторську підтримку в групах.

## Основні концепції

### Типи ботів для груп

**Бот з командами:**
- Реагує на команди типу `/command@mybot`
- Виконує конкретні дії за командами
- Використовує action для обробки команд

**Бот зі зверненнями:**
- Розпізнає звернення до себе через `@mybot`
- Може зберігати інформацію або передавати операторам
- Використовує перевірку тексту повідомлення

**Бот-слухач:**
- Слухає всі повідомлення в групі
- Передає повідомлення в операторську панель
- Дозволяє операторам відповідати від імені бота

### Налаштування Group Privacy

Для того, щоб бот міг слухати всі повідомлення в групі, потрібно вимкнути "Group Privacy" в BotFather:
1. Відкрити BotFather
2. Обрати бота
3. "Bot Settings" → "Group Privacy"
4. Вимкнути "Group Privacy"

## Варіанти підходів

### Команди vs звернення vs слухач

**Команди:**
- ✅ Плюси: Чітка структура, легко обробляти
- ❌ Мінуси: Обмежена гнучкість

**Звернення:**
- ✅ Плюси: Більш природна взаємодія
- ❌ Мінуси: Потрібна обробка тексту

**Слухач:**
- ✅ Плюси: Повний контроль, можливість операторської підтримки
- ❌ Мінуси: Потрібна налаштування Group Privacy

**Чому використовуємо різні підходи:**
Кожен підхід підходить для різних сценаріїв використання та потреб клієнтів.

## Прийняті рішення

### Використання Action для обробки

Для обробки команд та звернень використовуються Action блоки, які:
- Аналізують текст повідомлення
- Визначають тип команди або звернення
- Повертають події для переходу по сценарію

### Передача в операторську панель

Для передачі повідомлень в операторську панель використовується action `operator_panel__connect_to_operator_with_msg`, який дозволяє:
- Створити чат в операторській панелі
- Передати дані про повідомлення та користувача
- Дозволити оператору відповідати від імені бота

## Наслідки для користувачів і імплементації

### Для інтеграторів

При створенні ботів для груп важливо:

1. **Налаштувати Group Privacy** — для ботів-слухачів вимкнути Group Privacy в BotFather
2. **Створити Action для обробки** — для команд та звернень
3. **Налаштувати передачу в операторську панель** — якщо потрібна операторська підтримка
4. **Обробити різні типи повідомлень** — текстові, медіа, команди

### Типові помилки

**Помилка:** Бот не реагує на команди  
**Проблема:** Не налаштовані команди в BotFather або неправильна обробка в Action  
**Рішення:** Перевірити налаштування команд та Action обробку

**Помилка:** Бот не бачить повідомлення в групі  
**Проблема:** Не вимкнено Group Privacy  
**Рішення:** Вимкнути Group Privacy в BotFather

**Помилка:** Оператор не може відповідати від імені бота  
**Проблема:** Не налаштована передача в операторську панель  
**Рішення:** Використати `operator_panel__connect_to_operator_with_msg` для створення чату

## Приклади використання

### Обробка команди

```javascript
const action_handle_command = function() {
    const j = this.getCurrentStateJSON();
    const command = j.user_request?.text || '';
    
    if (command === '/start@mybot') {
        return 'start';
    } else if (command === '/help@mybot') {
        return 'help';
    }
    
    return 'unknown';
};
```

### Перевірка звернення

```javascript
const action_check_mention = function() {
    const j = this.getCurrentStateJSON();
    const message = j.user_request?.text || '';
    const bot_username = 'mybot';
    
    if (message.includes(`@${bot_username}`)) {
        return 'mentioned';
    }
    
    return 'not_mentioned';
};
```

## Пов'язані документи

- **Reference:** [Telegram Bot API Documentation](https://core.telegram.org/bots/api#available-methods) — офіційна документація Telegram про ботів
- **Explanation:** [Підключення чату з оператором](/uk/operatorline/explanation/connect-chat-to-operator.md) — передача повідомлень в операторську панель