Alerty Discord dla skracacza URL: konfiguracja Telegram, payloady, typowe pułapki

Gdy krótki link zaczyna zwracać 404 o 3 w nocy, chcesz mieć alert w tym samym czacie, w którym przebywa Twój dyżurujący. Dla większości zespołów inżynierskich to Discord; dla zespołów ops i growth w Europie często jest to Telegram. Elido dostarcza integracje Beta dla obu. Ten artykuł wyjaśnia, co wkleić, jaki JSON trafia na drugi koniec i jakie trzy scenariusze awarii zaskakują zespoły w pierwszym tygodniu.

Dwa fakty na wstępie. Po pierwsze, oba konektory działają wyłącznie przez wklejenie tokenu. Generujesz URL webhooka lub token bota w interfejsie dostawcy, wprowadzasz go do Elido i integracja jest aktywna. Nic nie konfigurujemy automatycznie po stronie Discord czy Telegram, ponieważ ich API tego nie obsługują. Po drugie, każdy alert jest generowany przez ten sam event bus, który obsługuje funkcję webhooków, więc kontrakty payloadów są stabilne i udokumentowane.

Dlaczego te dwa są w Beta, a nie w Live

Katalog integracji Elido oznacza integracje jako Live, gdy możemy zrobić dla Ciebie trzy rzeczy jednym kliknięciem: zarejestrować zasób dostawcy, przypisać odpowiednie scope'y i usunąć go przy rozłączeniu. Notion, Linear i Pipedrive spełniają te wymagania, ponieważ udostępniają OAuth wraz z API zasobów.

Webhooki Discord i boty Telegram nie. API webhooków Discord wymaga użytkownika-bota z uprawnieniem Manage Webhooks na konkretnym kanale - nie ma przepływu zgody, który moglibyśmy przeprowadzić. Telegram jest jeszcze trudniejszy: BotFather to interfejs oparty na czacie bez możliwości maszynowego wystawiania tokenów. Dlatego prosimy Cię o 90 sekund konfiguracji po stronie dostawcy, a my zajmujemy się wszystkim po tym. Token trafia do naszego zaszyfrowanego kopertowo magazynu i nigdy nie opuszcza dispatchera webhook api-core.

Odznaka Beta oznacza: "to działa, payloady są stabilne, ale UX połączenia/rozłączenia wymaga jednego dodatkowego kroku". Jeśli potrzebujesz auto-provisioningu już dziś, Slack ma status Live i działa na tym samym pipeline'ie transformerów.

Przewodnik po konfiguracji: najpierw Discord

W Discord otwórz docelowy kanał, kliknij ikonę koła zębatego i wybierz Integracje -> Webhooki -> Nowy Webhook. Nadaj mu nazwę taką jak elido-alerts, opcjonalnie wgraj avatar Elido z /blog/covers i skopiuj URL webhooka. Wygląda tak:

https://discord.com/api/webhooks/123456789012345678/AbCdEf-tokenstring

Ten URL to sekret. Każdy, kto go zna, może publikować na Twoim kanale. Traktuj go jak hasło.

W Elido przejdź do Ustawień przestrzeni roboczej -> Integracje -> Discord. Wklej URL, wybierz typy zdarzeń z listy wielokrotnego wyboru (broken_link, click_threshold, scan_failure, redirect_chain_change, qr_scan_anomaly) i zapisz. Formularz najpierw uruchamia syntetyczne zdarzenie testowe; jeśli Discord zwróci cokolwiek innego niż 204, zapis się nie powiedzie i wyświetlimy błąd bezpośrednio w formularzu.

Telegram wymaga dwóch kroków. Otwórz czat z BotFather, uruchom /newbot, nadaj mu nazwę i skopiuj token. Wygląda tak: 7891234567:AAH-tokenstring. Następnie dodaj bota do czatu, na którym chcesz otrzymywać alerty (prywatny czat, grupa lub kanał) i wyślij dowolną wiadomość. W Elido wklej token, kliknij "Znajdź czaty", wybierz z listy czatów widocznych przez bota i zapisz.

Krok "Znajdź czaty" raz wywołuje getUpdates Telegram, aby wyliczyć chat ID widoczne dla Twojego bota. Jeśli lista jest pusta, bot został dodany, ale nie otrzymał jeszcze wiadomości - wyślij jedną i spróbuj ponownie.

Rzeczywista struktura payloadu

Tu większość poradników na temat "alertów w czacie" staje się ogólnikowa. Oto co faktycznie dociera.

Dla Discord wysyłamy jeden embed na zdarzenie, nie przestarzały ciąg content. Transformer w services/api-core/internal/webhooks/delivery/transformers.go buduje tę strukturę:

{
  "username": "Elido",
  "embeds": [
    {
      "title": "Broken link detected",
      "description": "https://elido.me/launch -> 404 Not Found",
      "color": 15548997,
      "timestamp": "2026-06-04T09:14:22.000Z",
      "fields": [
        { "name": "Slug", "value": "launch", "inline": true },
        { "name": "Workspace", "value": "acme-prod", "inline": true },
        { "name": "Status", "value": "404", "inline": true },
        { "name": "First seen", "value": "2026-06-04 09:13:11 UTC" },
        { "name": "Last 5 redirects", "value": "blocked since 09:13:11" }
      ],
      "footer": { "text": "Elido alerts - broken_link" },
      "url": "https://elido.app/links/launch"
    }
  ]
}

Liczba całkowita color to dziesiętna wartość kodu szesnastkowego. Używamy czterech poziomów ważności: info 3447003 (niebieski), success 2280516 (zielony), warn 15844367 (bursztynowy), error 15548997 (czerwony). Więcej o tym mapowaniu za chwilę.

Telegram działa inaczej. Używamy parse_mode: "HTML", ponieważ Markdown V2 wymaga eskejpowania kilkunastu znaków i szybko staje się nieczytelny. Wywołanie sendMessage wygląda tak:

{
  "chat_id": -1001234567890,
  "parse_mode": "HTML",
  "disable_web_page_preview": true,
  "text": "<b>Broken link detected</b>\n<code>elido.me/launch</code> -> 404\n\nSlug: <code>launch</code>\nWorkspace: <code>acme-prod</code>\nFirst seen: 2026-06-04 09:13:11 UTC\n\n<a href=\"https://elido.app/links/launch\">Open in Elido</a>"
}

Ustawiamy disable_web_page_preview na true, aby czat nie puchł, gdy URL alertu rozwijałby podgląd. Podglądy linków w wątku dyżurowym są rozpraszające.

Oba transporty są ponawiane z tym samym backoffem: 1s, 5s, 30s, 5min, 30min. Po pięciu błędach integracja jest automatycznie wstrzymana i wysyłany jest e-mail. Każdą próbę logujemy do ClickHouse, dostępne przez przewodnik po observability.

Mapowanie ważności na kolor

Kolor to jedyny sygnał, który użytkownicy Discord widzą na pierwszy rzut oka. Wybraliśmy cztery poziomy ważności i stosujemy je spójnie we wszystkich integracjach obsługujących kolor:

• info (#3B82F6, niebieski) - nowy link utworzony przez API, pierwsze skanowanie miejsca docelowego, opublikowanie strony bio. Niewymagający działania, tylko informacyjny.
• success (#22C55E, zielony) - sprawdzanie linków przywrócone, certyfikat odnowiony dla domeny niestandardowej, osiągnięcie progu konwersji.
• warn (#F59E0B, bursztynowy) - współczynnik kliknięć 3x powyżej 7-dniowej wartości bazowej, łańcuch przekierowań wzrósł z 2 do 4 hopów, prędkość skanowania QR spadła o 80%. Warto rzucić ludzkim okiem.
• error (#EF4444, czerwony) - broken_link, scan_failure (Google Safe Browsing oflagował Twój cel), wygasły TLS domeny niestandardowej, dispatcher webhook poddał się po 5 próbach.

Telegram nie renderuje kolorów, dlatego wstawiamy na początku wiadomości emoji dopasowane do poziomu: niebieski diament, zielony ptaszek, żółte ostrzeżenie, czerwony krzyżyk. Ta sama semantyka, inny transport. Jeśli chcesz filtrować alerty Telegram w kliencie tylko do czerwonych zdarzeń, szukaj krzyżyka w tekście.

Typowe scenariusze awarii (i jak je rozpoznać)

W produkcji pojawiają się trzy rodzaje problemów. Są łatwe do naprawienia, gdy wiesz, czego szukać.

Limit szybkości Discord na gadatliwym webhookum. Discord ogranicza każdy URL webhooka do 50 żądań na sekundę i ok. 30/minutę w trybie ciągłym. Podepnij webhook do każdego click_threshold wirusowej kampanii, a limit zostanie przekroczony. Objawy: alerty przychodzą w partiach z 30-60-sekundowymi przerwami, odpowiedzi 429 w logu integracji. Rozwiązanie: włącz throttle per zdarzenie (domyślnie wyłączone), aby zdarzenia wywołane w ciągu 10-sekundowego okna były łączone w jeden embed.

Tryb prywatności bota Telegram. Tryb prywatności jest domyślnie włączony dla nowych botów i dotyczy tylko wiadomości, które bot może odczytać w grupach. Wychodzące wywołania sendMessage nie są nim objęte. Prawdziwa pułapka: gdy dodasz bota do grupy, Telegram wymaga, by bot otrzymał co najmniej jedną wiadomość, zanim getUpdates zwróci ten chat_id. Jeśli "Znajdź czaty" zwraca pustą listę, wyślij botowi dowolną wiadomość i spróbuj ponownie. W przypadku kanałów (nie grup) dodaj bota jako administratora z uprawnieniem do publikowania - nie ma potrzeby wysyłania wiadomości.

Rotacja tokenu. Oba transporty przechowują sekret zaszyfrowany przez warstwę szyfrowania kopertowego z ADR-0036. Tekst jawny nigdy nie trafia do Postgresa ani logów. Gdy token wycieknie (zrzut ekranu na Slacku, wpis w logu audytu Discord którego nie powinno być), rotacja to dwa kliknięcia: unieważnienie u dostawcy, wklejenie nowej wartości w Elido. Wiersz integracji, filtry zdarzeń i historia ClickHouse pozostają nienaruszone, ponieważ są powiązane z UUID integracji, nie z sekretem.

Kiedy wybrać który

Jeśli Twój zespół żyje w Discord, używaj Discord. Format embed jest bogatszy, pola inline renderują się przewidywalnie na komputerze i telefonie, a kolorowy poziom ważności masz gratis.

Jeśli Twój zespół jest na Telegram (typowe dla europejskich zespołów ops, zespołów deweloperskich z Europy Wschodniej i produktów kryptograficznych), używaj Telegram. API getUpdates i sendMessage jest banalnie proste, a tryb HTML pokrywa 95% potrzeb formatowania.

Jeśli potrzebujesz obu, używaj obu. Każda integracja to oddzielny wiersz z własnym filtrem zdarzeń, więc możesz kierować zdarzenia o ważności error do Discord, a ostrzeżenia do telegramowej grupy "szumu tła". Mamy klientów, którzy robią dokładnie to.

Dla wszystkiego poza czatem - aktualizacje CRM, automatyzacja marketingu, pipeline'y BI - Zapier i API webhooków to właściwe narzędzia. Czat jest dla ludzi reagujących na zdarzenia. Webhooki są dla systemów reagujących na zdarzenia.

Do czego nie powinieneś ich używać

Nie używaj Discord ani Telegram jako jedynego monitora link-rot. Czat jest efemeryczny. Jeśli alert przewinie się podczas intensywnego launchu, nie znajdziesz go ponownie. Używaj czatu jako warstwy wysokosygnałowej nad prawdziwym stosem observability: sprawdzacz linków Elido do syntetycznych kontroli, Datadog lub Sentry do śladów, a czat do zdarzeń, które człowiek naprawdę musi zobaczyć.

Nie umieszczaj danych osobowych w payloadach alertów. Domyślny payload zawiera slug linku i ID przestrzeni roboczej, nigdy IP kliknięcia ani identyfikatora odwiedzającego. Jeśli dołączasz niestandardowe metadane przez API i te metadane zawierają dane osobowe, trafią one do historii czatu Discord lub Telegram. Żaden z tych dostawców nie figuruje na liście DPA większości firm. Ogranicz się do danych operacyjnych.

Co jest w planach

Automatyczne provisioning dla Discord jest możliwe, jeśli wdrożymy się jako bot Discord zamiast konsumenta webhooka. Mamy prototyp. Kluczem jest umożliwienie użytkownikom przyznania botowi Elido dostępu do kanału przez przepływ zgody podobny do OAuth, po czym tworzymy webhook po stronie serwera. Nie ma tego w planie na kolejny kwartał, ale przeniosłoby Discord do statusu Live.

Telegram nie ma czystej ścieżki. BotFather to interfejs tylko dla ludzi, więc pełne automatyczne provisioning jest wykluczone. Aktualizacje planów znajdziesz w changelogu.

Potrzebujesz platformy czatu, której jeszcze nie obsługujemy (Mattermost? Microsoft Teams przez Power Automate?), napisz do zespołu na /about. Plany i limity miejsc są na stronie cennika; Discord i Telegram są dostępne od planu Pro wzwyż.