Torna al blog

Notifiche Telegram bot vs API push per gli alert degli sviluppatori

Notifiche Telegram bot vs API push per gli alert degli sviluppatori

Chiedi a un gruppo di sviluppatori come ricevono gli alert dai propri script e metà risponderà "un bot Telegram". È gratuito, Telegram è già sul telefono e il primo messaggio si configura in dieci minuti.

È anche un'app di chat che fa il lavoro di un cercapersone. Funziona finché l'alert importante non arriva nello stesso flusso delle chat di gruppo, o finché un nome file con un underscore non rompe il messaggio. Questo articolo illustra con onestà il setup di Telegram, dove regge, dove no, e come appare lo stesso alert tramite un'API di notifiche push.

Il setup di Telegram, dall'inizio alla fine

  1. Crea il bot. Scrivi a @BotFather, invia /newbot, scegli un nome e uno username che termini con bot. Ricevi un token come 110201543:AAH....
  2. Salutalo per primo. I bot non possono avviare una conversazione, quindi apri il bot e inviagli un messaggio qualsiasi. Per un gruppo, aggiungi il bot al gruppo.
  3. Trova il tuo chat id. Chiama getUpdates e leggi message.chat.id dal risultato:
curl -s "https://api.telegram.org/bot$TG_TOKEN/getUpdates" | jq '.result[].message.chat.id'

Gli aggiornamenti vengono conservati per 24 ore, e getUpdates smette di funzionare una volta impostato un webhook sul bot. Gli id dei gruppi sono negativi, e quelli dei supergruppi iniziano con -100.

  1. Invia l'alert:
curl -s "https://api.telegram.org/bot$TG_TOKEN/sendMessage" \
  -d chat_id="$TG_CHAT_ID" \
  -d text="Backup failed on db-01"

Questa è l'intera integrazione: due segreti in un file d'ambiente e una chiamata HTTP.

Dove Telegram funziona bene

  • Non costa nulla. La FAQ di Telegram afferma che i bot possono scrivere ai propri utenti senza costi.
  • È dove sei tu. Client per telefono, desktop e web, tutti sincronizzati.
  • I gruppi sono gratuiti. Aggiungi il bot a una chat di team e tutti vedono l'alert e possono discuterne nello stesso thread.
  • Lo hai già aperto. Nessuna nuova app, nessun nuovo account.

Per notifiche a basso impatto, come "il report notturno è pronto", è difficile fare di meglio.

Dove diventa scomodo

Ogni alert suona uguale

La Bot API ha esattamente un controllo di consegna: disable_notification, che invia un messaggio senza suono. Non esistono priorità, livelli time-sensitive né nulla che superi Non disturbare. Un backup fallito alle 3 di notte arriva nello stesso modo di uno sticker in una chat di gruppo, e se silenzi la chat per evitare il rumore, silenzi anche gli alert.

La formattazione ti darà problemi

Con parse_mode=MarkdownV2, i caratteri _ * [ ] ( ) ~ > # + - = | { } . ! e il backtick devono essere tutti preceduti da una barra rovesciata quando sono fuori dalla formattazione. Gli alert sono pieni proprio di questi caratteri: nomi di file, numeri di versione, URL, stack trace. Un solo punto non escapato in db-01.internal e Telegram rifiuta il messaggio con un errore 400, quindi anche l'alert sul fallimento fallisce. La modalità HTML è più sicura, ma devi comunque escapare <, > e & in tutto ciò che invii.

Il token è il bot

Il token va nel percorso dell'URL di ogni richiesta, e la documentazione di Telegram lo dice chiaramente: chiunque lo possieda può controllare il tuo bot. In pratica quell'URL finisce nella cronologia della shell, nei log della CI e in qualsiasi altro posto dove vengano annotati gli URL delle richieste. Se trapela, /token in BotFather ne genera uno nuovo, e a quel punto ogni script va aggiornato.

I pulsanti richiedono un bot in esecuzione

I pulsanti inline possono aprire un URL, e va bene. Un pulsante che esegue un'azione, come "riavvia il servizio", usa callback_data, e il tocco mostra una rotellina finché il bot non risponde. Questo significa un processo in ascolto degli aggiornamenti 24 ore su 24, più di quanto un cron job voglia gestire.

I picchi colpiscono i rate limit

Telegram chiede ai bot di restare sotto un messaggio al secondo per chat, e sotto 20 messaggi al minuto in un gruppo. Se un webhook molto attivo punta a un gruppo, ricevi 429 Too Many Requests con un valore retry_after, proprio quando le cose vanno male e gli alert arrivano più in fretta.

I servizi non possono scrivere direttamente

GitHub, Stripe, Grafana e Sentry inviano webhook con il proprio JSON. La Bot API vuole un chat_id e un text. Serve qualcosa in mezzo che traduca: un piccolo server, una funzione serverless, oppure un flusso n8n o Zapier. Questo relay è un'altra cosa da tenere in esecuzione.

Gli alert vivono in un messenger

I messaggi del bot sono normali messaggi di chat Telegram, conservati da Telegram e mescolati alle tue chat personali. Cercare gli incidenti del mese scorso significa scorrere una chat, non filtrare una cronologia per fonte.

Lo stesso alert tramite un'API push

Ecco l'alert del backup inviato con Pocket Alert, con una priorità e un pulsante che apre il log del job:

curl -X POST https://api.pocketalert.app/v1/messages \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Backup failed",
    "message": "db-01.internal: pg_dump exited with code 1",
    "level": "high",
    "actions": [{ "type": "view", "label": "Open log", "value": "https://ci.example.com/jobs/4821" }]
  }'

Cosa cambia:

  • Un solo segreto, in un header. Una chiave API nell'header Token, non un token nell'URL più un chat id.
  • Testo semplice in ingresso, testo semplice in uscita. Nessuna regola di escape. Punti, underscore e parentesi arrivano così come sono.
  • Priorità per messaggio. silent, low, default, high o critical. Su iPhone, high e critical passano da Full immersion come notifiche time-sensitive, e su Android un alert critical scavalca Non disturbare. Vedi alert critici.
  • Pulsanti senza bot. Fino a tre pulsanti di azione: aprire un URL, chiamare un endpoint HTTP o copiare un valore. Nulla deve restare in ascolto dei tocchi.
  • I servizi inviano direttamente. Ogni webhook ha il proprio URL. GitHub o Grafana inviano il proprio JSON, e segnaposto come %alerts.0.labels.alertname% portano i campi nella notifica. Ogni chiamata viene registrata nella cronologia dei webhook.
  • Una cronologia tutta sua. Gli alert sono conservati in un'app e in una dashboard separate, raggruppati per applicazione, non mescolati alle tue chat.

Quando Telegram resta la scelta migliore

Per essere equi:

  • Volume con budget ridotto. Telegram è gratuito, senza quote giornaliere oltre ai suoi rate limit. Il piano gratuito di Pocket Alert prevede 50 messaggi al giorno; per di più servono i piani a pagamento da 6 $ al mese.
  • Alert che avviano una conversazione. Se lo scopo è che un team discuta un alert nel punto in cui arriva, una chat di gruppo lo fa e una notifica push no.
  • Prima desktop e web. Se lavori su un laptop, il client desktop di Telegram mostra gli alert dove guardi già. Le app di Pocket Alert sono per iPhone e Android, con una dashboard web per la cronologia.

Una suddivisione che funziona per molti team: tieni un gruppo Telegram per le conversazioni e i riepiloghi giornalieri, e invia come push con un livello tutto ciò che deve svegliare qualcuno.

FAQ

Un messaggio di un bot Telegram può aggirare Non disturbare?

Non dal lato del bot. La Bot API non ha impostazioni di priorità, solo disable_notification per rendere silenzioso un messaggio. L'unico modo per passare Full immersion su iPhone è che il destinatario consenta Telegram come eccezione dell'app, il che lascia passare tutte le notifiche di Telegram, non solo gli alert.

Come trovo il mio chat id di Telegram?

Invia un messaggio qualsiasi al tuo bot, poi chiama https://api.telegram.org/bot<token>/getUpdates e leggi message.chat.id. Se il risultato è vuoto, l'aggiornamento potrebbe avere più di 24 ore, oppure il bot ha un webhook impostato, e getUpdates non funziona finché ne è attivo uno.

Perché il mio alert Telegram fallisce con un errore 400?

Di solito a causa di un carattere non escapato in modalità MarkdownV2 o HTML. Rimuovi parse_mode per inviare testo semplice, oppure escapa ogni carattere riservato prima dell'invio.

Un'API di notifiche push è più difficile da configurare di un bot Telegram?

Più o meno uguale. Con Pocket Alert installi l'app, copi una chiave API dalla dashboard e invii una sola POST. Non c'è alcun chat id da cercare né alcun bot da creare.

Posso inviare a entrambi?

Sì. Molti team tengono Telegram per la discussione e inviano come push gli alert che richiedono una risposta. Uno script può chiamare entrambe le API, e la maggior parte dei servizi che inviano webhook accetta più di un URL.

Crea un account gratuito su Pocket Alert e invia il curl qui sopra, oppure leggi prima cos'è un'API di notifiche push. Se stai valutando altre opzioni, il hub di confronto copre Pushover, ntfy, Bark, Gotify e altro ancora.

Condividi questo articolo