Telegram | Documentação Elven

Este guia tem como objetivo apresentar os passos necessários para configurar um contact point do tipo Telegram na Elven Observability, permitindo que as notificações de alertas sejam enviadas diretamente a um grupo do Telegram. Essa configuração visa disponibilizar um canal complementar de aviso, útil em situações que demandam comunicação técnica imediata.

A configuração de um contact point do tipo Telegram permite entregar a notificação diretamente do ambiente de alertas ao grupo escolhido, sem etapas intermediárias.

Essa entrega não percorre o fluxo de gestão de incidentes: o evento não é registrado como incidente, não admite reconhecimento e não compõe os indicadores de atendimento. Avalie antes se o objetivo é um canal complementar de comunicação técnica ou a notificação formal de plantão — para o segundo caso, a integração adequada é a do Telegram no âmbito do time, disponível na documentação do Elven Incident.

Pré-requisitos no Telegram

Diferentemente da integração no âmbito do time, este caminho utiliza um bot próprio, criado e mantido por quem realiza a configuração.

Crie o bot no BotFather. No Telegram, localize o perfil @BotFather, envie o comando /newbot e informe o nome de exibição e o nome de usuário do bot. O nome de usuário deve ser único e terminar em bot.
Registre o token fornecido. Ao concluir a criação, o BotFather apresenta o token de acesso do bot. Esse token é uma credencial de acesso e deve receber o mesmo tratamento atribuído a uma senha.
Crie o grupo e adicione o bot. Crie o grupo que receberá as notificações e adicione o bot criado como participante. O Telegram não permite que um bot ingresse em um grupo por conta própria.
Obtenha o identificador do grupo. O identificador pode ser consultado por meio do endpoint getUpdates da API do Telegram, após o envio de um comando no grupo.

É fundamental assegurar que o bot esteja presente no grupo antes de realizar o teste da configuração. Caso contrário, o Telegram recusa o envio e a notificação não é entregue.

Cabe observar que, por padrão, um bot em grupo recebe apenas mensagens que constituam comandos ou respostas diretas a ele. Em consequência, uma mensagem comum enviada no grupo não é apresentada na consulta ao getUpdates. Recomenda-se enviar um comando, como /start, para que a consulta retorne o identificador desejado.

Acessando a Configuração de Contact Points

No menu de navegação, acesse a seção Alerting.
Selecione a opção Contact points. É aqui que você pode visualizar e gerenciar todos os pontos de contato configurados no ambiente.
Selecione a opção de adicionar um novo contact point.

Criando o Contact Point do Telegram

No formulário de criação, informe os campos a seguir.

Em Name, informe um nome descritivo, que será utilizado como referência nas políticas de notificação.
Em Integration, selecione a opção Telegram.
Em BOT API Token, informe o token obtido nos pré-requisitos.
Em Chat ID, informe o identificador do grupo do Telegram.

É fundamental assegurar que o identificador informado no campo Chat ID inclua o sinal negativo. A interface indica apenas que o campo espera um identificador numérico, sem especificar essa característica. Identificadores de grupo no Telegram são negativos, enquanto identificadores positivos correspondem a conversas individuais. Quando um identificador positivo é informado, o Telegram interpreta o destino como uma conversa individual inexistente para o bot, e o envio é recusado com o retorno 400 Bad Request.

Recomenda-se ainda avaliar, no momento da criação, se o grupo será convertido em supergrupo. Grupos comuns são convertidos automaticamente em supergrupos quando crescem ou quando recebem um link público, e essa conversão altera o identificador do grupo. Caso o identificador anterior permaneça registrado no contact point, as notificações deixam de ser entregues sem que haja aviso.

Configurações Opcionais

A seção Optional Telegram settings disponibiliza parâmetros adicionais de envio, entre os quais o parse_mode, responsável pela interpretação da formatação da mensagem.

Mensagens no Telegram estão limitadas a 4096 caracteres. Quando um parse_mode diferente de None está definido e a mensagem excede esse limite, o truncamento pode interromper uma marcação de formatação e produzir uma mensagem inválida, resultando em falha no envio. Em cenários nos quais os alertas apresentam descrições extensas, recomenda-se definir o parse_mode como None, privilegiando a confiabilidade da entrega em relação à formatação.

Testando a Integração

O formulário disponibiliza a opção de teste, que envia uma notificação ao destino configurado sem a necessidade de aguardar o disparo de um alerta real.

Ao selecionar Send test notification, a plataforma apresenta o resultado da tentativa. A confirmação Test notification sent successfully indica que o envio foi aceito pelo Telegram. Recomenda-se verificar, além da mensagem de confirmação, se a notificação foi efetivamente recebida no grupo.

Concluído o teste, selecione Save contact point para registrar a configuração.

Roteando Alertas para o Contact Point

O registro do contact point não determina, por si, quais alertas serão enviados a ele. O direcionamento é definido de duas formas.

Por meio das Notification policies, criando uma rota que corresponda a determinadas labels do alerta e indicando o contact point como destinatário.
Diretamente na regra de alerta, na seção de notificações, indicando o contact point como destinatário.

Recomenda-se estabelecer um critério de severidade no direcionamento, reservando o canal para eventos que demandem atenção imediata. O envio indiscriminado de notificações ao grupo tende a reduzir a atenção da equipe ao canal.

Glossário de Termos Técnicos

Telegram: Aplicativo de mensagens instantâneas, utilizado neste contexto como canal de recebimento de notificações de alertas.

Contact point: Destino configurado no ambiente de alertas para o envio de notificações. Cada contact point possui um tipo de integração e os parâmetros correspondentes.

Notification policy: Configuração que define como os alertas são agrupados e para quais contact points são direcionados, a partir das labels que carregam.

Bot (Telegram): Aplicação automatizada que opera dentro do Telegram. Para enviar mensagens a um grupo, um bot precisa ser previamente adicionado como participante.

BotFather: Perfil oficial do Telegram utilizado para criar e administrar bots, por meio do qual é obtido o token de acesso.

BOT API Token: Credencial que autoriza o envio de mensagens em nome do bot. Deve receber o mesmo tratamento atribuído a uma senha.

Chat ID: Identificador numérico do destino da mensagem no Telegram. Em grupos, esse número é negativo.

Grupo (Telegram): Conversa com múltiplos participantes no Telegram, utilizada como destino coletivo das notificações.

Supergrupo (Telegram): Modalidade de grupo do Telegram destinada a um número maior de participantes e a recursos adicionais, como link público. A conversão de um grupo comum em supergrupo altera o identificador do grupo.

getUpdates: Endpoint da API do Telegram que retorna os eventos recebidos pelo bot, utilizado para consultar o identificador de um grupo.

parse_mode: Parâmetro que define como a formatação da mensagem será interpretada pelo Telegram.

Label: Par de chave e valor associado a uma regra de alerta, utilizado para classificação, busca, silenciamento e roteamento.

Alerta: Notificação gerada a partir de uma condição monitorada que foi atendida, indicando desvio em relação ao comportamento esperado.

Incidente: Evento inesperado que pode impactar a operação de sistemas ou serviços, demandando atenção e resolução imediata.

Reconhecimento (ack): Registro de que um responsável assumiu a ciência do evento, utilizado no cálculo dos indicadores de atendimento.