Avvisi Discord per accorciatore URL: configurazione Telegram, payload, insidie comuni

Se un link abbreviato inizia a rispondere con 404 alle 3 di notte, vuoi l'avviso nella stessa chat dove il tuo team di turno è già presente. Per la maggior parte dei team di sviluppo è Discord; per i team ops e growth in Europa è spesso Telegram. Elido include integrazioni Beta per entrambi. Questo articolo illustra cosa incollare, quale JSON arriva dall'altra parte e i tre scenari di guasto che sorprendono i team nella prima settimana.

Due premesse. Prima: entrambi i connettori funzionano solo tramite incolla-token. Generi un URL di webhook o un token bot nell'interfaccia del provider, lo inserisci in Elido e l'integrazione è attiva. Non provisioniamo nulla automaticamente lato Discord o Telegram perché le loro API non offrono questa possibilità. Seconda: ogni avviso è guidato dallo stesso bus di eventi che alimenta la funzionalità webhooks, quindi i contratti di payload sono stabili e documentati.

Perché questi due sono in Beta e non in Live

Il catalogo integrazioni di Elido segna le integrazioni come Live quando possiamo fare tre cose per te con un clic: registrare la risorsa del provider, associare gli scope corretti e rimuoverla alla disconnessione. Notion, Linear e Pipedrive si qualificano perché espongono OAuth insieme a una API di risorse.

I webhook Discord e i bot Telegram non lo fanno. La Webhooks API di Discord richiede un utente bot con permesso Gestisci webhook su un canale specifico; nessun flusso di consenso che possiamo pilotare. Telegram è peggio ancora: BotFather è un'interfaccia basata su chat senza emissione di token leggibile da macchina. Per questo ti chiediamo di dedicare 90 secondi alla configurazione lato provider, e ci occupiamo noi di tutto il resto. Il token è conservato nel nostro store con cifratura a busta e non lascia mai il dispatcher webhook di api-core.

Il badge Beta significa: "funziona, i payload sono stabili, ma l'UX di connessione/disconnessione richiede un passaggio aggiuntivo." Se hai bisogno dell'auto-provisioning oggi, Slack è Live e gira sullo stesso pipeline di transformer.

Guida alla configurazione: prima Discord

In Discord, apri il canale di destinazione, clicca sull'icona a ingranaggio e seleziona Integrazioni -> Webhook -> Nuovo Webhook. Dagli un nome come elido-alerts, carica facoltativamente l'avatar Elido da /blog/covers e copia l'URL del webhook. Ha questo aspetto:

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

Quell'URL è il segreto. Chiunque la possieda può pubblicare nel tuo canale. Trattala come una password.

Tornando in Elido, vai in Impostazioni workspace -> Integrazioni -> Discord. Incolla l'URL, seleziona i tipi di evento dalla selezione multipla (broken_link, click_threshold, scan_failure, redirect_chain_change, qr_scan_anomaly) e salva. Il modulo esegue prima un evento di test sintetico; se Discord restituisce qualcosa di diverso da 204, il salvataggio fallisce e l'errore viene mostrato direttamente.

Telegram richiede due passaggi. Apri una chat con BotFather, esegui /newbot, dagli un nome e copia il token. Ha questo formato: 7891234567:AAH-tokenstring. Poi aggiungi il bot alla chat in cui vuoi ricevere gli avvisi (chat privata, gruppo o canale) e invia qualsiasi messaggio. In Elido, incolla il token, clicca su "Trova chat", scegli dall'elenco delle chat visibili al bot e salva.

Il passaggio "Trova chat" chiama getUpdates di Telegram una volta per elencare i chat ID che il tuo bot ha già visto. Se l'elenco è vuoto, il bot è stato aggiunto ma non ha ancora ricevuto messaggi - invianegli uno e riprova.

La struttura reale del payload

Qui la maggior parte dei tutorial "avvisi in chat" si fa vaga. Ecco cosa arriva davvero.

Per Discord inviamo un singolo embed per evento, non la stringa content legacy. Il transformer in services/api-core/internal/webhooks/delivery/transformers.go costruisce questa struttura:

{
  "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"
    }
  ]
}

L'intero color è il valore decimale del codice esadecimale. Usiamo quattro livelli di severità: info 3447003 (blu), success 2280516 (verde), warn 15844367 (ambra), error 15548997 (rosso). Maggiori dettagli su questa mappatura tra poco.

Telegram è diverso. Usiamo parse_mode: "HTML" perché Markdown V2 richiede l'escape di una dozzina di caratteri e diventa rapidamente complicato. La chiamata sendMessage ha questo aspetto:

{
  "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>"
}

Impostiamo disable_web_page_preview a true per evitare che la chat si gonfi quando l'URL dell'avviso genererebbe altrimenti un'anteprima. Le anteprime inline dei link sono fastidiose in un thread di reperibilità.

Entrambi i trasporti vengono ritentati con lo stesso backoff: 1s, 5s, 30s, 5min, 30min. Dopo cinque fallimenti l'integrazione viene messa in pausa automaticamente e viene inviata un'email. Registriamo ogni tentativo su ClickHouse, consultabile tramite la guida all'osservabilità.

Mappatura severità - colore

Il colore è l'unico segnale che gli utenti Discord colgono a colpo d'occhio. Abbiamo scelto quattro livelli di severità e li manteniamo coerenti su tutte le integrazioni che supportano il colore:

• info (#3B82F6, blu) - nuovo link creato via API, prima scansione di una destinazione, pagina bio pubblicata. Non richiede azione, solo informativa.
• success (#22C55E, verde) - il link checker si è ripreso, certificato rinnovato per un dominio personalizzato, soglia di conversione raggiunta.
• warn (#F59E0B, ambra) - il tasso di clic è 3x la baseline degli ultimi 7 giorni, la catena di redirect è cresciuta da 2 a 4 hop, la velocità di scansione QR è calata dell'80%. Vale uno sguardo umano.
• error (#EF4444, rosso) - broken_link, scan_failure (Google Safe Browsing ha segnalato la tua destinazione), TLS del dominio personalizzato scaduto, il dispatcher webhook ha rinunciato dopo 5 tentativi.

Telegram non gestisce i colori, quindi prefissiamo il messaggio con un emoji che corrisponde: diamante blu, spunta verde, avviso giallo, croce rossa. Stessa semantica, trasporto diverso. Se vuoi filtrare gli avvisi Telegram nel tuo client solo agli eventi rossi, cerca l'emoji croce nel testo.

Modalità di guasto comuni (e come individuarle)

In produzione si presentano tre problemi. Sono facili da risolvere una volta che sai cosa cercare.

Rate limit Discord su un webhook molto attivo. Discord limita ogni URL di webhook a 50 richieste al secondo e circa 30/minuto in modo sostenuto. Collega un webhook a ogni click_threshold di una campagna virale e ci arriverai. Sintomi: gli avvisi arrivano in lotti con un ritardo di 30-60 secondi, risposte 429 nel log di integrazione. Soluzione: attiva il throttle per evento (disattivato per default) per consolidare gli eventi che si attivano entro una finestra di 10 secondi in un unico embed.

Modalità privacy del bot Telegram. La modalità privacy è attiva per default sui nuovi bot e riguarda solo i messaggi che il bot può leggere nei gruppi. Le chiamate sendMessage in uscita non sono interessate. La vera insidia: quando aggiungi il bot a un gruppo, Telegram richiede che il bot riceva almeno un messaggio prima che getUpdates restituisca quel chat_id. Se "Trova chat" risulta vuoto, invia al bot qualsiasi messaggio e riprova. Per i canali (non i gruppi), aggiungi il bot come amministratore con i permessi di pubblicazione, senza la danza del messaggio iniziale.

Rotazione del token. Entrambi i trasporti memorizzano il segreto cifrato tramite il livello di cifratura a busta di ADR-0036. Il testo in chiaro non risiede mai in Postgres né nei log. Quando un token viene compromesso (screenshot su Slack, voce nel log di audit Discord che non dovrebbe esistere), la rotazione si fa in due clic: revocare dal provider, incollare il nuovo valore in Elido. La riga di integrazione, i filtri degli eventi e la cronologia ClickHouse restano intatti perché si basano sull'UUID di integrazione, non sul segreto.

Quando scegliere quale

Se il tuo team vive su Discord, usa Discord. Il formato embed è più ricco, i campi inline si visualizzano in modo prevedibile su desktop e mobile, e ottieni gratuitamente i colori per severità.

Se il tuo team usa Telegram (comune per i team ops europei, i team di sviluppatori dell'Europa orientale e i prodotti legati alle criptovalute), usa Telegram. L'API getUpdates e sendMessage è semplicissima, e la modalità HTML copre il 95% delle esigenze di formattazione.

Se hai bisogno di entrambi, usali entrambi. Ogni integrazione è una riga separata con il proprio filtro eventi, quindi puoi instradare gli eventi di severità error verso Discord e gli avvisi verso un gruppo Telegram di "rumore di fondo". Alcuni nostri clienti fanno esattamente così.

Per tutto ciò che è fuori dalla chat - aggiornamenti CRM, automazione marketing, pipeline BI - Zapier e l'API webhooks sono gli strumenti giusti. La chat è per gli esseri umani che reagiscono agli eventi. I webhook sono per i sistemi che reagiscono agli eventi.

Per cosa non dovresti usarli

Non usare Discord o Telegram come unico monitor di link-rot. La chat è effimera. Se l'avviso scorre via durante un lancio intenso, non lo ritroverai. Usa la chat come livello ad alto segnale sopra un vero stack di osservabilità: il link checker di Elido per i controlli sintetici, Datadog o Sentry per i trace, e la chat per gli eventi che un umano deve davvero vedere.

Non inserire dati personali nei payload degli avvisi. Il payload predefinito contiene lo slug del link e l'ID del workspace, mai l'IP del clic né l'identificatore del visitatore. Se alleghi metadati personalizzati via API e quei metadati contengono dati personali, finiranno nella cronologia della chat di Discord o Telegram. Nessuno dei due provider compare nella lista DPA della maggior parte delle aziende. Attieniti ai dati operativi.

Cosa c'è nella roadmap

L'auto-provisioning per Discord è possibile se lo implementiamo come bot Discord invece che come consumer di webhook. Lo abbiamo prototipato. La chiave è permettere agli utenti di concedere al bot Elido l'accesso a un canale tramite un flusso di consenso simile a OAuth, dopodiché creiamo il webhook lato server. Non è nel piano del prossimo trimestre, ma porterebbe Discord in Live.

Telegram non ha una strada pulita. BotFather è un'interfaccia solo per umani, quindi l'auto-provisioning completo è fuori discussione. Gli aggiornamenti della roadmap si trovano nel changelog.

Hai bisogno di una piattaforma chat che non supportiamo ancora (Mattermost? Microsoft Teams via Power Automate?), contatta il team su /about. I piani e i limiti di posti sono nella pagina dei prezzi; sia Discord che Telegram sono disponibili dal piano Pro in su.