Voltar para o blog

Notificações do bot do Telegram vs API de push para alertas de desenvolvedor

Notificações do bot do Telegram vs API de push para alertas de desenvolvedor

Pergunte a uma sala de desenvolvedores como eles recebem alertas de seus scripts e metade vai dizer "um bot do Telegram". Ele é gratuito, o Telegram já está no celular e a primeira mensagem leva dez minutos para ser configurada.

Mas também é um aplicativo de chat fazendo o trabalho de um pager. Isso funciona até o alerta que importa chegar no meio dos grupos de conversa, ou até um nome de arquivo com sublinhado quebrar a mensagem. Este post percorre a configuração do Telegram com honestidade, mostra onde ela funciona, onde não funciona e como o mesmo alerta fica por meio de uma API de notificação push.

A configuração do Telegram, do início ao fim

  1. Crie o bot. Envie uma mensagem para @BotFather, mande /newbot e escolha um nome e um nome de usuário terminado em bot. Você recebe um token como 110201543:AAH....
  2. Mande um oi primeiro. Bots não podem iniciar uma conversa, então abra o bot e envie qualquer mensagem. Para um grupo, adicione o bot ao grupo.
  3. Encontre seu chat id. Chame getUpdates e leia message.chat.id no resultado:
curl -s "https://api.telegram.org/bot$TG_TOKEN/getUpdates" | jq '.result[].message.chat.id'

As atualizações são mantidas por 24 horas, e getUpdates para de funcionar assim que um webhook é configurado no bot. Os ids de grupos são negativos, e os ids de supergrupos começam com -100.

  1. Envie o alerta:
curl -s "https://api.telegram.org/bot$TG_TOKEN/sendMessage" \
  -d chat_id="$TG_CHAT_ID" \
  -d text="Backup failed on db-01"

Essa é a integração inteira: dois segredos em um arquivo de ambiente e uma chamada HTTP.

Onde o Telegram funciona bem

  • Não custa nada. O próprio FAQ do Telegram diz que bots podem enviar mensagens para seus usuários sem custo.
  • Está em todo lugar onde você está. Clientes para celular, desktop e web, tudo sincronizado.
  • Grupos são gratuitos. Adicione o bot a um chat de equipe e todos veem o alerta e podem conversar sobre ele na mesma thread.
  • Você já tem o app aberto. Nenhum app novo, nenhuma conta nova.

Para notificações de baixo risco, como "o relatório noturno está pronto", é difícil superar.

Onde fica incômodo

Todo alerta soa igual

A Bot API tem exatamente um controle de entrega: disable_notification, que envia a mensagem sem som. Não há prioridade, nenhum nível de tempo sensível, nada que passe pelo Não perturbe. Um backup que falhou às 3 da manhã chega do mesmo jeito que uma figurinha em um grupo, e se você silenciar o chat para fugir do barulho, silencia os alertas junto.

A formatação vai te dar problemas

Com parse_mode=MarkdownV2, os caracteres _ * [ ] ( ) ~ > # + - = | { } . ! e o acento grave precisam ser escapados com uma barra invertida fora da formatação. Alertas estão cheios desses caracteres: nomes de arquivo, números de versão, URLs, stack traces. Um ponto sem escape em db-01.internal e o Telegram rejeita a mensagem com erro 400, então o alerta sobre a falha também falha. O modo HTML é mais seguro, mas você ainda precisa escapar <, > e & em tudo que envia.

O token é o bot

O token vai no caminho da URL de cada requisição, e a documentação do Telegram deixa claro: quem tiver o token pode controlar seu bot. Na prática, essa URL acaba no histórico do shell, nos logs de CI e em qualquer outro lugar onde URLs de requisição são registradas. Se ele vazar, /token no BotFather emite um novo, e aí todos os scripts precisam ser atualizados.

Botões precisam de um bot rodando

Botões inline podem abrir uma URL, o que é tranquilo. Um botão que executa algo, como "reiniciar o serviço", usa callback_data, e o toque mostra um spinner até o seu bot responder. Isso significa um processo escutando atualizações o tempo todo, mais do que uma tarefa cron gostaria de manter.

Rajadas batem nos limites de taxa

O Telegram pede que bots fiquem abaixo de uma mensagem por segundo por chat, e de 20 mensagens por minuto em um grupo. Aponte um webhook falante para um grupo e você recebe 429 Too Many Requests com um valor retry_after, justamente quando as coisas estão dando errado e os alertas chegam mais rápido.

Serviços não conseguem postar diretamente

GitHub, Stripe, Grafana e Sentry enviam webhooks com seu próprio JSON. A Bot API espera um chat_id e um text. Algo precisa ficar no meio e fazer a tradução: um servidor pequeno, uma função serverless ou um fluxo no n8n ou no Zapier. Esse intermediário é mais uma coisa para manter rodando.

Os alertas ficam dentro de um mensageiro

Mensagens de bot são mensagens comuns de chat do Telegram, armazenadas pelo Telegram e misturadas com suas conversas pessoais. Pesquisar os incidentes do mês passado significa rolar um chat, não filtrar um histórico por origem.

O mesmo alerta por meio de uma API push

Aqui está o alerta de backup enviado para o Pocket Alert, com uma prioridade e um botão que abre o log do 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" }]
  }'

O que muda:

  • Um segredo, em um cabeçalho. Uma chave de API no cabeçalho Token, não um token na URL mais um chat id.
  • Texto simples entra, texto simples sai. Sem regras de escape. Pontos, sublinhados e colchetes chegam como estão.
  • Prioridade por mensagem. silent, low, default, high ou critical. No iPhone, high e critical passam pelo Foco como notificações de tempo sensível, e no Android um alerta critical sobrepõe o Não perturbe. Veja alertas críticos.
  • Botões sem bot. Até três botões de ação: abrir uma URL, chamar um endpoint HTTP ou copiar um valor. Nada precisa ficar escutando os toques.
  • Serviços postam diretamente. Cada webhook tem sua própria URL. GitHub ou Grafana enviam o próprio JSON, e placeholders como %alerts.0.labels.alertname% puxam campos para dentro da notificação. Cada chamada fica registrada no histórico de webhooks.
  • Um histórico próprio. Os alertas ficam em um app e um painel separados, agrupados por aplicativo, não misturados com as suas conversas.

Quando o Telegram ainda é a melhor escolha

Sendo justo:

  • Volume com orçamento limitado. O Telegram é gratuito, sem cota diária além dos seus limites de taxa. O plano gratuito do Pocket Alert é de 50 mensagens por dia; mais que isso exige um plano pago a partir de US$ 6 por mês.
  • Alertas que começam uma conversa. Se a ideia é que a equipe discuta um alerta onde ele chega, um grupo de chat faz isso e uma notificação push não.
  • Desktop e web primeiro. Se você vive no notebook, o cliente de desktop do Telegram mostra os alertas onde você já olha. Os apps do Pocket Alert são para iPhone e Android, com um painel web para o histórico.

Uma divisão que funciona para muitas equipes: mantenha um grupo no Telegram para conversas e resumos diários, e envie como push, com um nível, qualquer coisa que precise acordar alguém.

FAQ

Uma mensagem de bot do Telegram consegue passar pelo Não perturbe?

Não pelo lado do bot. A Bot API não tem configuração de prioridade, só disable_notification para deixar a mensagem silenciosa. A única forma de passar pelo Foco no iPhone é o destinatário liberar o Telegram como exceção de app, o que deixa passar todas as notificações do Telegram, não só os alertas.

Como encontro meu chat id do Telegram?

Envie qualquer mensagem para o seu bot e depois chame https://api.telegram.org/bot<token>/getUpdates e leia message.chat.id. Se o resultado estiver vazio, a atualização pode ter mais de 24 horas, ou o bot pode ter um webhook configurado, e getUpdates não funciona enquanto houver um.

Por que meu alerta do Telegram falha com erro 400?

Geralmente por um caractere sem escape no modo MarkdownV2 ou HTML. Remova o parse_mode para enviar texto simples, ou escape todos os caracteres reservados antes de enviar.

Uma API de notificações push é mais difícil de configurar do que um bot do Telegram?

Quase o mesmo. Com o Pocket Alert você instala o app, copia uma chave de API do painel e envia um POST. Não há chat id para procurar nem bot para criar.

Posso enviar para os dois?

Sim. Muitas equipes mantêm o Telegram para discussões e enviam como push os alertas que exigem uma resposta. Um script pode chamar as duas APIs, e a maioria dos serviços que enviam webhooks aceita mais de uma URL.

Crie uma conta gratuita no Pocket Alert e envie o curl acima, ou leia primeiro o que é uma API de notificações push. Se você está avaliando outras opções, o hub de comparações cobre Pushover, ntfy, Bark, Gotify e mais.

Compartilhe este artigo