Alertas Discord para encurtador de URL: configuração do Telegram, payloads, armadilhas comuns

Se um link curto começa a retornar 404 às 3 da manhã, você quer o alerta no mesmo chat onde o seu plantão já está ativo. Para a maioria das equipes de engenharia, isso é o Discord; para equipes de ops e crescimento na Europa, frequentemente é o Telegram. O Elido oferece integrações Beta para os dois. Este artigo explica o que colar, qual JSON chega do outro lado e os três modos de falha que pegam as equipes de surpresa na primeira semana.

Dois fatos logo de cara. Primeiro, os dois conectores funcionam apenas por colagem de token. Você gera uma URL de webhook ou token de bot na interface do fornecedor, insere no Elido e a integração fica ativa. Não provisionamos nada automaticamente no lado do Discord ou Telegram porque as APIs deles não expõem essa capacidade. Segundo, cada alerta é gerado pelo mesmo event bus que alimenta o recurso de webhooks, portanto os contratos de payload são estáveis e documentados.

Por que esses dois estão em Beta e não em Live

O catálogo de integrações do Elido marca as integrações como Live quando conseguimos fazer três coisas por você com um clique: registrar o recurso do fornecedor, vincular os scopes corretos e removê-lo na desconexão. Notion, Linear e Pipedrive se qualificam porque expõem OAuth mais uma API de recursos.

Webhooks do Discord e bots do Telegram, não. A Webhooks API do Discord precisa de um usuário bot com permissão Manage Webhooks em um canal específico; não há fluxo de consentimento que possamos conduzir. O Telegram é pior: o BotFather é uma interface baseada em chat sem emissão de tokens legível por máquina. Por isso pedimos que você faça 90 segundos de configuração no lado do fornecedor, e nós cuidamos de tudo depois. O token fica no nosso armazenamento com criptografia de envelope e nunca sai do dispatcher de webhook do api-core.

O badge Beta significa: "isto funciona, os payloads são estáveis, mas a UX de conexão/desconexão requer um passo extra." Se você precisa de auto-provisioning hoje, o Slack é Live e roda no mesmo pipeline de transformers.

Guia de configuração: Discord primeiro

No Discord, abra o canal de destino, clique no ícone de engrenagem e escolha Integrações -> Webhooks -> Novo Webhook. Dê um nome como elido-alerts, opcionalmente carregue o avatar do Elido em /blog/covers e copie a URL do webhook. Ela tem esse aspecto:

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

Essa URL é o segredo. Qualquer um que a tenha pode publicar no seu canal. Trate-a como uma senha.

De volta ao Elido, vá para Configurações do workspace -> Integrações -> Discord. Cole a URL, escolha os tipos de evento na seleção múltipla (broken_link, click_threshold, scan_failure, redirect_chain_change, qr_scan_anomaly) e salve. O formulário executa primeiro um evento de teste sintético; se o Discord retornar algo diferente de 204, o salvamento falha e mostramos o erro diretamente.

O Telegram são dois passos. Abra um chat com o BotFather, execute /newbot, dê um nome e copie o token. Tem esse formato: 7891234567:AAH-tokenstring. Depois adicione o bot ao chat onde quer os alertas (chat privado, grupo ou canal) e envie qualquer mensagem. No Elido, cole o token, clique em "Encontrar chats", escolha da lista de chats que o bot pode ver e salve.

O passo "Encontrar chats" chama getUpdates do Telegram uma vez para enumerar os chat IDs que seu bot já viu. Se a lista estiver vazia, o bot foi adicionado mas nunca recebeu uma mensagem - envie uma e tente novamente.

A estrutura real do payload

Aqui é onde a maioria dos tutoriais de "alertas no chat" fica vaga. Isso é o que realmente chega.

Para o Discord enviamos um único embed por evento, não a string content legada. O transformer em services/api-core/internal/webhooks/delivery/transformers.go constrói esta estrutura:

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

O inteiro color é o decimal do código hexadecimal. Usamos quatro severidades: info 3447003 (azul), success 2280516 (verde), warn 15844367 (âmbar), error 15548997 (vermelho). Mais sobre esse mapeamento em instantes.

O Telegram é diferente. Usamos parse_mode: "HTML" porque o Markdown V2 exige escapar uma dúzia de caracteres e fica feio rápido. A chamada sendMessage tem esse aspecto:

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

Definimos disable_web_page_preview como true para que o chat não inche quando a URL do alerta geraria uma prévia. Prévias de links inline são ruidosas em um thread de plantão.

Ambos os transportes são refeitos com o mesmo backoff: 1s, 5s, 30s, 5min, 30min. Após cinco falhas, a integração é pausada automaticamente e um e-mail é enviado. Registramos cada tentativa no ClickHouse, consultável pelo guia de observabilidade.

Mapeamento de severidade para cor

Cor é o único sinal que os usuários do Discord percebem de relance. Escolhemos quatro severidades e as mantemos consistentes em todas as integrações que suportam cor:

• info (#3B82F6, azul) - novo link criado via API, primeiro scan de um destino, página bio publicada. Sem ação necessária, apenas informativo.
• success (#22C55E, verde) - verificador de links recuperado, certificado renovado para um domínio personalizado, limiar de conversão atingido.
• warn (#F59E0B, âmbar) - taxa de cliques 3x acima da baseline de 7 dias, cadeia de redirecionamentos cresceu de 2 para 4 hops, velocidade de scan QR caiu 80%. Vale uma verificação humana.
• error (#EF4444, vermelho) - broken_link, scan_failure (Google Safe Browsing sinalizou seu destino), TLS de domínio personalizado expirado, dispatcher de webhook desistiu após 5 tentativas.

O Telegram não renderiza cores, então prefixamos a mensagem com um emoji que corresponde: diamante azul, visto verde, aviso amarelo, cruz vermelha. Mesma semântica, transporte diferente. Se quiser filtrar alertas do Telegram no cliente apenas para eventos vermelhos, procure o emoji de cruz no texto.

Modos de falha comuns (e como identificá-los)

Três coisas dão errado em produção. São fáceis de resolver uma vez que você sabe o que procurar.

Rate limit do Discord em um webhook movimentado. O Discord limita cada URL de webhook a 50 requisições por segundo e aproximadamente 30/minuto de forma sustentada. Conecte um webhook a cada click_threshold de uma campanha viral e você vai atingir o limite. Sintomas: alertas chegam em lotes com intervalo de 30 a 60 segundos, respostas 429 no log de integração. Correção: ative o throttle por evento (desativado por padrão) para consolidar eventos disparados dentro de uma janela de 10 segundos em um único embed.

Modo de privacidade do bot do Telegram. O modo de privacidade está ativado por padrão para novos bots e afeta apenas quais mensagens o bot pode ler em grupos. Chamadas sendMessage de saída não são afetadas. A verdadeira armadilha: quando você adiciona o bot a um grupo, o Telegram exige que o bot receba pelo menos uma mensagem antes de getUpdates retornar aquele chat_id. Se "Encontrar chats" retornar vazio, envie qualquer mensagem ao bot e tente novamente. Para canais (não grupos), adicione o bot como administrador com permissões de publicação, sem necessidade de mensagem prévia.

Rotação de token. Ambos os transportes armazenam o segredo criptografado pela camada de criptografia de envelope do ADR-0036. Texto simples nunca fica no Postgres ou nos logs. Quando um token vaza (captura de tela no Slack, entrada no log de auditoria do Discord que não deveria existir), a rotação são dois cliques: revogar no fornecedor, colar o novo valor no Elido. A linha de integração, os filtros de eventos e o histórico do ClickHouse permanecem intactos porque são indexados pelo UUID de integração, não pelo segredo.

Quando escolher qual

Se sua equipe vive no Discord, use o Discord. O formato de embed é mais rico, os campos inline renderizam previsivelmente em desktop e mobile, e você ganha severidade por cor gratuitamente.

Se sua equipe usa Telegram (comum para equipes de ops europeias, equipes de desenvolvedores na Europa Oriental, e produtos ligados a cripto), use o Telegram. A API de getUpdates e sendMessage é extremamente simples, e o modo HTML cobre 95% das necessidades de formatação.

Se precisar dos dois, use os dois. Cada integração é uma linha separada com seu próprio filtro de eventos, então você pode rotear eventos de severidade error para o Discord e avisos para um grupo do Telegram de "ruído de fundo". Temos clientes fazendo exatamente isso.

Para tudo fora do chat - atualizações de CRM, automação de marketing, pipelines de BI - Zapier e a API de webhooks são as ferramentas certas. Chat é para humanos reagindo a eventos. Webhooks são para sistemas reagindo a eventos.

Para o que você não deve usá-los

Não use Discord ou Telegram como único monitor de link-rot. Chat é efêmero. Se o alerta passar despercebido durante um lançamento intenso, você não o encontrará de novo. Use o chat como camada de alto sinal sobre um stack de observabilidade real: o link checker do Elido para verificações sintéticas, Datadog ou Sentry para traces, e o chat para os eventos que um humano realmente precisa ver.

Não coloque dados pessoais nos payloads de alertas. O payload padrão tem o slug do link e o ID do workspace, nunca o IP do clique ou o identificador do visitante. Se você anexar metadados personalizados via API e esses metadados contiverem dados pessoais, eles acabarão no histórico de chat do Discord ou Telegram. Nenhum dos fornecedores está na lista de DPA da maioria das empresas. Fique com dados operacionais.

O que está no roadmap

Auto-provisioning para Discord é possível se nos implantarmos como bot Discord em vez de consumidor de webhook. Temos um protótipo. A chave é permitir que os usuários concedam ao bot do Elido acesso a um canal com um fluxo de consentimento no estilo OAuth, após o qual criamos o webhook no lado do servidor. Não está no plano do próximo trimestre, mas isso mudaria o Discord para Live.

O Telegram não tem um caminho limpo. O BotFather é uma interface apenas para humanos, então o auto-provisioning completo está fora de cogitação. Atualizações do roadmap ficam no changelog.

Precisa de uma plataforma de chat que ainda não suportamos (Mattermost? Microsoft Teams via Power Automate?), fale com a equipe em /about. Planos e limites de assentos estão na página de preços; Discord e Telegram estão disponíveis no plano Pro e acima.