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
- Crie o bot. Envie uma mensagem para
@BotFather, mande/newbote escolha um nome e um nome de usuário terminado embot. Você recebe um token como110201543:AAH.... - 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.
- Encontre seu chat id. Chame
getUpdatese leiamessage.chat.idno 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.
- 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,highoucritical. 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.