Alertas de Discord para acortador de URL: configuración de Telegram, payloads, errores comunes

Si un enlace corto empieza a devolver 404 a las 3 de la madrugada, quieres la alerta en el mismo chat donde ya está tu guardia de turno. Para la mayoría de los equipos de ingeniería, eso es Discord; para los equipos de operaciones y crecimiento en Europa, suele ser Telegram. Elido incluye integraciones Beta para ambos. Este artículo explica qué pegar, qué JSON llega al otro extremo y los tres modos de fallo que sorprenden a los equipos la primera semana.

Dos datos por adelantado. Primero, ambos conectores funcionan únicamente mediante pegado de token. Generas una URL de webhook o un token de bot en la interfaz del proveedor, lo introduces en Elido y la integración queda activa. No aprovisionamos nada automáticamente en el lado de Discord o Telegram porque sus APIs no exponen esa capacidad. Segundo, cada alerta es impulsada por el mismo bus de eventos que alimenta la función de webhooks, por lo que los contratos de payload son estables y están documentados.

Por qué estos dos están en Beta y no en Live

El catálogo de integraciones de Elido marca las integraciones como Live cuando podemos hacer tres cosas por ti con un clic: registrar el recurso del proveedor, adjuntar los scopes correctos y eliminarlo al desconectar. Notion, Linear y Pipedrive cumplen los requisitos porque exponen OAuth más una API de recursos.

Los webhooks de Discord y los bots de Telegram no lo hacen. La API de Webhooks de Discord necesita un usuario bot con permiso de Gestionar Webhooks en un canal específico; no hay flujo de consentimiento que podamos manejar. Telegram es peor: BotFather es una interfaz basada en chat sin emisión de tokens legible por máquinas. Por eso te pedimos que realices 90 segundos de configuración en el lado del proveedor, y nosotros nos encargamos de todo lo demás. El token se guarda en nuestro almacén con cifrado de sobre y nunca sale del despachador de webhooks de api-core.

La etiqueta Beta significa: "esto funciona, los payloads son estables, pero la UX de conexión/desconexión requiere un paso adicional." Si necesitas aprovisionamiento automático hoy, Slack está en Live y funciona sobre el mismo pipeline de transformadores.

Guía de configuración: primero Discord

En Discord, abre el canal de destino, haz clic en el icono de engranaje y elige Integraciones -> Webhooks -> Nuevo Webhook. Dale un nombre como elido-alerts, sube opcionalmente el avatar de Elido desde /blog/covers y copia la URL del webhook. Tiene este aspecto:

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

Esa URL es el secreto. Cualquiera que la tenga puede publicar en tu canal. Trátala como una contraseña.

De vuelta en Elido, ve a Configuración del espacio de trabajo -> Integraciones -> Discord. Pega la URL, elige los tipos de evento en la selección múltiple (broken_link, click_threshold, scan_failure, redirect_chain_change, qr_scan_anomaly) y guarda. El formulario ejecuta primero un evento de prueba sintético; si Discord devuelve algo distinto de 204, el guardado falla y te mostramos el error en línea.

Telegram son dos pasos. Abre un chat con BotFather, ejecuta /newbot, ponle nombre y copia el token. Tiene esta forma: 7891234567:AAH-tokenstring. Luego añade el bot al chat donde quieres las alertas (chat privado, grupo o canal) y envía cualquier mensaje. En Elido, pega el token, haz clic en "Buscar chats", elige de la lista de chats que el bot puede ver y guarda.

El paso "Buscar chats" llama una vez a getUpdates de Telegram para enumerar los chat IDs que tu bot ha visto. Si la lista está vacía, el bot fue añadido pero nunca recibió un mensaje - envía uno y vuelve a intentarlo.

La estructura real del payload

Aquí es donde la mayoría de los tutoriales de "alertas en chat" se vuelven vagos. Esto es lo que llega en realidad.

Para Discord, enviamos un único embed por evento, no la cadena content heredada. El transformador en services/api-core/internal/webhooks/delivery/transformers.go construye esta estructura:

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

El entero color es el decimal del código hexadecimal. Usamos cuatro niveles de gravedad: info 3447003 (azul), success 2280516 (verde), warn 15844367 (ámbar), error 15548997 (rojo). Más sobre ese mapeo en un momento.

Telegram es diferente. Usamos parse_mode: "HTML" porque Markdown V2 requiere escapar una docena de caracteres y se vuelve difícil de leer muy rápido. La llamada a sendMessage tiene esta forma:

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

Establecemos disable_web_page_preview en true para que el chat no se expanda cuando la URL de la alerta generaría una vista previa. Las previsualizaciones de enlaces en línea son ruidosas en un hilo de guardia.

Ambos transportes se reintentan con el mismo backoff: 1s, 5s, 30s, 5min, 30min. Tras cinco fallos, la integración se pausa automáticamente y se envía un correo. Registramos cada intento en ClickHouse, consultable a través de la guía de observabilidad.

Mapeo de gravedad a color

El color es la única señal que los usuarios de Discord perciben de un vistazo. Elegimos cuatro niveles de gravedad y los mantenemos consistentes en todas las integraciones que admiten color:

• info (#3B82F6, azul) - nuevo enlace creado via API, primer escaneo de un destino, página bio publicada. No requiere acción, solo informativo.
• success (#22C55E, verde) - comprobador de enlaces recuperado, certificado renovado para un dominio personalizado, umbral de conversión alcanzado.
• warn (#F59E0B, ámbar) - la tasa de clics es 3x la línea base de 7 días, la cadena de redirección creció de 2 a 4 saltos, la velocidad de escaneo QR cayó un 80%. Merece una revisión humana.
• error (#EF4444, rojo) - broken_link, scan_failure (Google Safe Browsing marcó tu destino), TLS de dominio personalizado caducado, el despachador de webhooks se rindió tras 5 reintentos.

Telegram no renderiza colores, por lo que anteponemos a cada mensaje un emoji que coincide: diamante azul, marca verde, advertencia amarilla, cruz roja. Misma semántica, transporte diferente. Si quieres filtrar las alertas de Telegram en tu cliente para ver solo eventos rojos, busca el emoji de cruz en el texto.

Modos de fallo comunes (y cómo detectarlos)

En producción ocurren tres cosas. Son fáciles de solucionar una vez que sabes qué buscar.

Límite de velocidad de Discord en un webhook con mucho tráfico. Discord limita cada URL de webhook a 50 solicitudes por segundo y aproximadamente 30/minuto de forma sostenida. Conecta un webhook a cada click_threshold de una campaña viral y lo superarás. Síntomas: las alertas llegan en lotes con un hueco de 30-60 segundos, respuestas 429 en el registro de integración. Solución: activa el throttle por evento (desactivado por defecto) para agrupar los eventos disparados en una ventana de 10 segundos en un solo embed.

Modo de privacidad del bot de Telegram. El modo de privacidad está activado por defecto para los bots nuevos y solo afecta a los mensajes que el bot puede leer en grupos. Las llamadas salientes de sendMessage no se ven afectadas. El verdadero problema: cuando añades el bot a un grupo, Telegram requiere que el bot reciba al menos un mensaje antes de que getUpdates devuelva ese chat_id. Si "Buscar chats" devuelve vacío, envía al bot cualquier mensaje y vuelve a intentarlo. Para canales (no grupos), añade el bot como administrador con permisos de publicación, sin necesidad de enviar mensaje primero.

Rotación de tokens. Ambos transportes almacenan el secreto cifrado mediante la capa de cifrado de sobre de ADR-0036. El texto plano nunca reside en Postgres ni en los registros. Cuando un token se filtra (captura de pantalla en Slack, entrada en el registro de auditoría de Discord que no debería existir), la rotación son dos clics: revocar en el proveedor, pegar el nuevo valor en Elido. La fila de integración, los filtros de eventos y el historial de ClickHouse permanecen intactos porque se asocian al UUID de integración, no al secreto.

Cuándo elegir cuál

Si tu equipo vive en Discord, usa Discord. El formato de embed es más rico, los campos en línea se renderizan de forma predecible en escritorio y móvil, y obtienes gravedad por colores de forma gratuita.

Si tu equipo está en Telegram (común en equipos de operaciones europeos, equipos de desarrollo de Europa del Este y productos vinculados a las criptomonedas), usa Telegram. La API de getUpdates y sendMessage es muy sencilla, y el modo HTML cubre el 95% de las necesidades de formato.

Si necesitas ambos, usa ambos. Cada integración es una fila separada con su propio filtro de eventos, por lo que puedes enrutar eventos de severidad error a Discord y advertencias a un grupo de Telegram de "ruido de fondo". Hay clientes que hacen exactamente eso.

Para todo lo que está fuera del chat - actualizaciones de CRM, automatización de marketing, pipelines de BI - Zapier y la API de webhooks son las herramientas adecuadas. El chat es para humanos que reaccionan a eventos. Los webhooks son para sistemas que reaccionan a eventos.

Para qué no deberías usarlos

No uses Discord o Telegram como tu único monitor de link-rot. El chat es efímero. Si la alerta pasa de largo durante un lanzamiento intenso, no la encontrarás de nuevo. Usa el chat como capa de alta señal sobre un stack de observabilidad real: el comprobador de enlaces de Elido para comprobaciones sintéticas, Datadog o Sentry para trazas, y el chat para los eventos que un humano realmente necesita ver.

No incluyas PII en los payloads de alertas. El payload predeterminado tiene el slug del enlace y el ID del espacio de trabajo, nunca la IP del clic ni el identificador del visitante. Si adjuntas metadatos personalizados a través de la API y esos metadatos contienen datos personales, acabarán en el historial del chat de Discord o Telegram. Ninguno de los dos proveedores figura en la lista DPA de la mayoría de las empresas. Quédate con los datos operacionales.

Qué hay en el roadmap

El aprovisionamiento automático para Discord es posible si lo implementamos como bot de Discord en lugar de consumidor de webhook. Lo hemos prototipado. La clave es permitir que los usuarios otorguen acceso al canal del bot de Elido mediante un flujo de consentimiento tipo OAuth, tras lo cual creamos el webhook en el servidor. No está en el plan del próximo trimestre, pero convertiría Discord en Live.

Telegram no tiene un camino limpio. BotFather es una interfaz solo para humanos, por lo que el aprovisionamiento automático completo está descartado. Las actualizaciones del roadmap están en el changelog.

¿Necesitas una plataforma de chat que aún no soportamos (¿Mattermost? ¿Microsoft Teams via Power Automate?), escribe al equipo en /about. Los planes y límites de asientos están en la página de precios; tanto Discord como Telegram están disponibles en el plan Pro y superiores.