Discord url shortener alerts: Telegram setup, payloads, pitfalls

If a short link starts 404'ing at 3am, you want the alert in the same chat where your on-call already lives. For most engineering teams that is Discord; for ops and growth teams in Europe it is often Telegram. Elido ships Beta integrations for both. This piece walks through what you paste in, what JSON lands on the other end, and the three failure modes that catch teams the first week.

Two facts up front. First, both connectors are paste-token only. You generate a webhook URL or bot token in the vendor UI, drop it into Elido, and the integration is live. We do not auto-provision anything on the Discord or Telegram side because their APIs do not expose that capability. Second, every alert is driven by the same event bus that powers the webhooks feature, so the payload contracts are stable and documented.

Why these two are Beta and not Live#

Elido's integration catalog marks integrations Live when we can do three things for you in one click: register the vendor resource, attach the right scopes, and tear it down on disconnect. Notion, Linear, and Pipedrive qualify because they expose OAuth plus a resource API.

Discord webhooks and Telegram bots do not. The Discord Webhooks API needs a bot user with Manage Webhooks permission on a specific channel; no consent flow we can drive. Telegram is worse: BotFather is a chat-based UI with no machine-readable token issuance. So we ask you to do 90 seconds of vendor-side setup, and we own everything after. The token sits in our envelope-encrypted store and never leaves the api-core webhook dispatcher.

The Beta badge means "this works, the payloads are stable, but the connect/disconnect UX is one extra step." If you want auto-provision today, Slack is Live and runs on the same transformer pipeline.

Setup walkthrough: Discord first#

In Discord, open the target channel, click the gear icon, and pick Integrations -> Webhooks -> New Webhook. Give it a name like elido-alerts, optionally upload the Elido avatar from /blog/covers, and copy the webhook URL. It looks like:

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

That URL is the secret. Anyone with it can post to your channel. Treat it like a password.

Back in Elido, go to Workspace Settings -> Integrations -> Discord. Paste the URL, pick the event types from the multi-select (broken_link, click_threshold, scan_failure, redirect_chain_change, qr_scan_anomaly), and save. The form runs a synthetic test event first; if Discord returns anything other than 204, the save fails and we show you the error inline.

Telegram is two steps. Open a chat with BotFather, run /newbot, name it, and copy the token. It looks like 7891234567:AAH-tokenstring. Then add the bot to the chat you want alerts in (private chat, group, or channel) and send any message. In Elido, paste the token, click "Find chats," pick from the list of chats the bot can see, and save.

The "Find chats" step calls Telegram's getUpdates once to enumerate chat IDs your bot has seen. If the list is empty, the bot was added but never received a message - send one and retry.

The actual payload shape#

This is where most "alerts to chat" tutorials get vague. Here is what actually lands.

For Discord, we send a single embed per event, not the legacy content string. The transformer at services/api-core/internal/webhooks/delivery/transformers.go builds this shape:

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

The color integer is the decimal of the hex code. We use four severities: info 3447003 (blue), success 2280516 (green), warn 15844367 (amber), error 15548997 (red). More on that mapping in a minute.

Telegram is different. We use parse_mode: "HTML" because Markdown V2 requires escaping a dozen characters and it gets ugly fast. The sendMessage call looks like:

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

We set disable_web_page_preview to true so the chat does not balloon when the alert URL would otherwise unfurl. Inline link previews are noisy in an on-call thread.

Both transports get retried with the same backoff: 1s, 5s, 30s, 5min, 30min. After five failures the integration is auto-paused and an email goes out. We log every attempt to ClickHouse, queryable via the observability guide.

Severity to color mapping#

Color is the only signal Discord users see at a glance. We picked four severities and stuck to them across every integration that supports color:

• info (#3B82F6, blue) - new link created via API, first scan of a destination, bio-page published. Not actionable, just a heads-up.
• success (#22C55E, green) - link checker recovered, certificate renewed for a custom domain, conversion uplift threshold hit.
• warn (#F59E0B, amber) - click rate is 3x the 7-day baseline, redirect chain grew from 2 hops to 4, QR scan velocity dropped 80%. Worth a human glance.
• error (#EF4444, red) - broken_link, scan_failure (Google Safe Browsing flagged your destination), custom domain TLS expired, webhook dispatcher gave up after 5 retries.

Telegram does not render colors, so we prefix the message with an emoji that matches: blue diamond, green check, yellow warning, red cross. Same semantic, different transport. If you want to filter Telegram alerts in your client to only red events, grep the text for the cross emoji.

Common failure modes (and how to spot them)#

Three things go wrong in production. They are easy to fix once you know what to look for.

Discord rate-limit on a chatty webhook. Discord caps each webhook URL at 50 requests per second and ~30/minute sustained. Wire a webhook to every click_threshold on a viral campaign and you will hit it. Symptoms: alerts arrive in batches with a 30-60 second gap, 429 responses in the integration log. Fix: turn on the per-event throttle (default off) to coalesce events fired within a 10-second window into one embed.

Telegram bot privacy mode. Privacy mode is on by default for new bots and only affects what messages the bot can read in groups. Outbound sendMessage is unaffected. The real gotcha: when you add the bot to a group, Telegram requires the bot to receive at least one message before getUpdates will surface that chat_id. If "Find chats" returns empty, send the bot any message and retry. For channels (not groups), add the bot as an admin with post permissions, no message-first dance.

Token rotation. Both transports store the secret encrypted at rest via the envelope encryption layer from ADR-0036. Plaintext never lives in Postgres or logs. When a token leaks (screenshot in Slack, Discord audit log entry that should not exist), rotation is two clicks: revoke at the vendor, paste the new value in Elido. The integration row, event filters, and ClickHouse history all stay attached because they key off the integration UUID, not the secret.

When to pick which#

If your team lives in Discord, use Discord. The embed format is richer, the inline fields render predictably on desktop and mobile, and you get color severity for free.

If your team is on Telegram (common for Europe-based ops, developer teams in Eastern Europe, and crypto-adjacent products), use Telegram. The getUpdates and sendMessage API is dead simple, and HTML mode covers 95% of formatting needs.

If you need both, run both. Each integration is a separate row with its own event filter, so you can route error-severity events to Discord and warns to a Telegram "background noise" group. We have customers doing exactly that.

For everything outside chat - CRM updates, marketing automation, BI pipelines - Zapier and the webhooks API are the right tools. Chat is for humans reacting to events. Webhooks are for systems reacting to events.

What you should not use these for#

Do not use Discord or Telegram as your only link-rot monitor. Chat is ephemeral. If the alert scrolls past during a busy launch, you will not find it again. Wire chat as the high-signal layer on top of a real observability stack: Elido's link checker for synthetic checks, Datadog or Sentry for traces, and chat for the events a human actually needs to see.

Do not put PII in alert payloads. The default payload has the link slug and workspace ID, never the click IP or visitor identifier. If you attach custom metadata via the API and that metadata contains personal data, it ends up in Discord or Telegram chat history. Neither vendor is on most companies' DPA list. Stick to operational data.

What is on the roadmap#

Auto-provision for Discord is possible if we ship as a Discord bot rather than a webhook consumer. We have prototyped it. The unlock is letting users grant the Elido bot access to a channel with one OAuth-style consent flow, after which we create the webhook server-side. Not on next quarter's plan, but it would flip Discord to Live.

Telegram has no clean path. BotFather is a human-only UI, so full auto-provision is off the table. Roadmap updates live in the changelog.

Need a chat platform we don't support yet (Mattermost? Microsoft Teams via Power Automate?), ping the team at /about. Plans and seat limits are on the pricing page; both Discord and Telegram ship on the Pro plan and above.