Telegram-інтеграція — налаштування та використання

Один бот на проєкт. Кожен AI-воркер отримує власний топік у Telegram Supergroup — повідомлення автоматично маршрутизуються до потрібного воркера і відповідь повертається у той самий топік.

Як це виглядає в роботі

Supergroup "My Project"
├── 📌 General          ← загальний чат (без прив'язки)
├── 🔵 Developer        ← повідомлення → Developer воркер
└── 🟢 Consultant       ← повідомлення → Consultant воркер

Ти пишеш у топік Developer → Arc OS обробляє через Claude → відповідь з'являється в тому ж топіку.

Telegram і CRM Dashboard — це два канали до одного воркера. Можна почати діалог у Telegram, продовжити в CRM — контекст зберігається.

Налаштування

Крок 1 — Створити бота у BotFather

1. Відкрий @BotFather у Telegram
2. Надішли /newbot
3. Введи ім'я бота (наприклад: My Project)
4. Введи username — має закінчуватись на bot (наприклад: my_project_arc_bot)
5. BotFather поверне токен у форматі 123456789:AABBccDDee...

⚠️ Збережи токен — він потрібен при налаштуванні в CRM.

Крок 2 — Створити Supergroup з Topics

2.1 Створити групу

Telegram Desktop / Mobile:

1. Натисни іконку олівця → New Group
2. Додай будь-якого учасника (можна потім видалити)
3. Дай назву групі → Create

2.2 Увімкнути Topics

1. Відкрий налаштування групи (натисни на назву вгорі)
2. Edit → знайди розділ Topics
3. Увімкни перемикач — Telegram автоматично конвертує групу у Supergroup

2.3 Дізнатись Supergroup ID

Supergroup ID завжди починається з -100.

Варіант А — через @userinfobot:

1. Перешли будь-яке повідомлення з групи боту @userinfobot
2. Бот поверне ID у форматі -1001234567890

Варіант Б — через Telegram Web:

1. Відкрий групу на web.telegram.org
2. У адресному рядку буде URL виду #-1001234567890
3. Скопіюй число разом з мінусом

Крок 3 — Додати бота як адміністратора

1. Відкрий налаштування групи → Administrators
2. Add Admin → у пошуку введи @username_твого_бота (повний username з @)
3. Вибери бота зі списку → OK
4. Права за замовчуванням підходять — залиш як є

⚠️ Бот не з'явиться у пошуку якщо вводити неповний username або без @. Введи точний @username.

Крок 4 — Створити топіки для воркерів

У групі натисни + → New Topic:

• Назви топіки за воркерами: Developer, Consultant, або кастомні імена
• Можеш обрати кольори/іконки для зручності

Крок 5 — Підключити у CRM

1. Відкрий arc-os.co → вибери проєкт → Project Settings
2. Знайди розділ Channels → натисни Connect Telegram

5.1 Ввести дані бота

Натисни Verify & get topics.

5.2 Верифікація

CRM перевірить:

• ✅ Токен валідний
• ✅ Бот є адміністратором групи
• ✅ Список топіків завантажений

5.3 Прив'язати топіки до воркерів

Для кожного топіку вибери воркера з дропдауну:

Developer  →  [developer     ▾]
Consultant →  [consultant    ▾]
General    →  [(не прив'язано)]

Натисни Save bindings.

Крок 6 — Тест

1. Напиши будь-яке повідомлення у топік Developer
2. Бот відповість у тому ж топіку від Developer воркера
3. Повтори для Consultant

Щоденне використання

Робота через топіки (рекомендовано)

Просто пиши текст завдання у потрібний топік — ніяких префіксів не потрібно:

[Developer топік]
Виправи баг у формі логіну — поле email не валідується

[Consultant топік]
Проаналізуй архітектуру auth модуля, що можна покращити?

Якщо топік не прив'язаний до воркера — відповідає воркер за замовчуванням.

Команди в особистому чаті з ботом

В особистому чаті з ботом доступне ручне переключення воркерів через префікси:

Приклади:

/c Проаналізуй архітектуру auth модуля
/d Виправи баг у login формі
/w:sentinel Проведи security audit останніх змін

Повідомлення без префіксу йде до поточного активного воркера — після /d Виправ баг наступні повідомлення без префіксу теж підуть до Developer.

Inline кнопки під відповіддю

Після кожної відповіді AI-воркера з'являються кнопки керування:

Керування процесом:

Контекст та фідбек:

Навігація:

Контекст та пам'ять

• Кожен воркер має окрему пам'ять (до 50 повідомлень)
• Reply на повідомлення → його текст додається як контекст до запиту
• Context Router автоматично підбирає top-5 навичок, релевантних до твого повідомлення
• 👎 фідбек → система запам'ятовує помилку і враховує її в наступних запитах

Управляючі команди бота

Зв'язок з CRM Dashboard

Telegram топік  ──┐
                  ├──► Child Bot ──► Claude ──► Відповідь
CRM Dashboard   ──┘                              │
                                                 ▼
                                        Telegram + CRM (одночасно)

• Повідомлення з CRM обробляються кожні 500ms
• Відповіді з'являються і в Telegram, і в CRM одночасно
• Attachments (зображення, PDF) підтримуються через CRM Dashboard
• Можна почати діалог у Telegram, продовжити в CRM — контекст зберігається

Відключення бота

CRM → Project Settings → Channels → Disconnect.

Це видалить токен і всі прив'язки топіків. Бот залишиться у групі — видали його з адміністраторів вручну якщо потрібно.

Усунення проблем