Clovieod deleguj AI
Zacznij za darmo

Integracje

Telegram — przejęcie rozmowy

Jak podpiąć Telegram do Clovie, żeby konsultant mógł przejąć rozmowę z klientem na żywo.

Wymagania

  • Konto Telegram (dla każdego konsultanta)
  • Bot utworzony w @BotFather z ustawionym @username
  • Produkcyjny URL aplikacji (NEXT_PUBLIC_APP_URL) dostępny z internetu — Telegram musi dosięgnąć webhooka

1. Utwórz bota

  1. W Telegramie otwórz @BotFather
  2. /newbot → nazwa i username (np. mojafirma_support_bot)
  3. Skopiuj token API

2. Połącz bota w panelu

  1. Panel → Integracje → sekcja Telegram
  2. Wklej token → Połącz bota
  3. Backend waliduje token (getMe), zapisuje go zaszyfrowany i rejestruje webhook: https://clovie.pl/api/webhooks/telegram/{organizationId}?secret=...

3. Powiąż konto konsultanta

Każdy członek workspace, który ma odpowiadać z Telegrama:

  1. Integracje → Telegram → link Połącz mój Telegram (krótki deep link — limit Telegrama 64 znaki)
  2. Otwórz ten link w Telegramie (nie wyszukuj bota ręcznie)
  3. Jeśli nic się nie stanie — naciśnij Start na dole czatu
  4. Bot odpowiada: „✅ Konto powiązane…”

Powtórz dla wszystkich konsultantów w zespole.

4. Włącz w widgecie

  1. Konfigurator asystenta → krok Podstawy
  2. Włącz Poproś konsultanta
  3. Opublikuj asystenta

W widgecie pojawi się pole akcji, gdy handoffAvailable: true w API config (Telegram + ≥1 powiązany konsultant).

Przepływ

  1. Gość klika Poproś konsultanta → POST /api/v1/handoff/request (handoffStatus: requested)
  2. Wszyscy powiązani konsultanci dostają powiadomienie z przyciskiem Dołącz
  3. Konsultant klika Dołącz → active (tylko jeśli nie ma innej aktywnej rozmowy — max 1 na konsultanta)
  4. Dwukierunkowy czat: widget ↔ Telegram (polling w widgecie)
  5. Gość może Anuluj oczekiwanie w stanie requested → powrót do bot
  6. Konsultant kończy: Zakończ rozmowę lub /zakoncz → rozmowa closed w DB; w widgecie baner + Rozpocznij nową rozmowę

Typowe problemy

Objaw Rozwiązanie
Brak powiadomień Sprawdź powiązanie konta konsultanta; bot musi być połączony
Webhook nie działa lokalnie Użyj tunelu (Cloudflare) lub testuj na stagingu z publicznym HTTPS
handoff_unavailable w widgecie Włącz handoff w wizardzie + Telegram + co najmniej 1 konsultant
„Rozmowa już przejęta” Inny konsultant kliknął Dołącz pierwszy
„Masz już aktywną rozmowę” (Telegram) Zakończ bieżącą rozmowę (/zakoncz) przed przejęciem kolejnej
„Nie udało się poprosić…” / brak przycisku Rozmowa closed → Rozpocznij nową rozmowę; sprawdź Origin (403) lub rate limit (429)
Historia rozmów pusta / 401 Middleware musi mieć publiczną trasę /api/v1/conversations (bez Clerk)
Link powiązania nie działa Użyj linku z panelu (krótki token w Redis — limit deep linku 64 znaki)

Powiązane