Telegram

Este guia tem como objetivo apresentar os passos necessários para integrar a Elven Platform com o Telegram, permitindo que as notificações de alertas e incidentes sejam entregues diretamente em um grupo do Telegram. Essa integração visa aproximar a notificação do canal em que o time já se comunica, reduzindo o tempo entre a ocorrência do evento e a ciência da equipe responsável.

A integração entre a Elven Platform e o Telegram permite direcionar as notificações de alertas e incidentes a um grupo específico de responsáveis, garantindo que o aviso alcance a equipe de plantão no momento em que o evento acontece. Além disso, essa integração contribui para manter o ciclo completo de gestão do incidente, uma vez que a notificação parte da própria plataforma e preserva o registro, o reconhecimento e as métricas de atendimento.

Pré-requisitos no Telegram

Antes de iniciar a configuração na Elven Platform, é necessário preparar o grupo que receberá as notificações.

• Crie o grupo no Telegram que será utilizado como destino das notificações. O Telegram exige a inclusão de ao menos um outro participante no momento da criação.
• Adicione o bot GlorfindelBot ao grupo. Este é o bot responsável pelo envio das mensagens pela Elven Platform. Para adicioná-lo, acesse o nome do grupo, selecione a opção de adicionar membros e busque por GlorfindelBot.
• Obtenha o identificador do grupo. O identificador de grupos no Telegram é um número negativo, e será solicitado durante a configuração da integração.

Recomenda-se 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 na integração, as notificações deixam de ser entregues sem que haja aviso.

Acessando a Configuração de Integração ao Telegram

• No menu superior da tela, acesse a opção People. Em seguida, selecione Teams.
• Selecione o time que deve receber as notificações. As integrações de canais de comunicação são configuradas por time, e não por usuário.
• Clique na aba Integrations for notifications. É aqui que você pode visualizar e gerenciar todos os canais de notificação disponíveis para o time.

Criando a Integração com o Telegram

Localize o cartão Telegram group entre os canais disponíveis. O cartão apresenta o estado atual da integração, que pode ser Not Integrated ou Integrated.

Ao iniciar o processo de integração, será exibida a janela Integration with Telegram group, solicitando o preenchimento de um único campo obrigatório. Nesse campo deve ser informado o identificador do grupo do Telegram, obtido nos pré-requisitos, incluindo o sinal negativo.

Após confirmar o preenchimento, selecione Save. O cartão da integração passará a exibir o estado Integrated, indicando que o canal está registrado para o time.

Configurando as Regras de Notificação

Concluir a integração registra o canal, mas não define o que será enviado por ele. A definição do conteúdo é feita na aba Notification Rules, no mesmo time.

Nessa aba é possível selecionar quais tipos de notificação serão direcionados a cada canal, entre alertas, incidentes e turnos de plantão. Recomenda-se reservar o Telegram para eventos que exigem atenção imediata, direcionando notificações informativas a canais assíncronos, como o e-mail. A ausência dessa distinção tende a produzir um volume elevado de mensagens no grupo, o que reduz a atenção da equipe ao canal e compromete a finalidade da integração.

Requisito de Severidade nos Alertas

Para que a notificação seja processada, o alerta deve conter a label severity, grafada em minúsculas. A label é definida na regra de alerta, na seção Labels, e também pode ser informada na janela de teste de um contact point.

A label de severidade é o elemento que permite à plataforma classificar o evento. Alertas que chegam sem essa informação são registrados como not-classified, condição em que não é possível estabelecer prioridade entre eventos — um alerta relativo a pagamentos e um erro de coleta passam a competir pela mesma atenção da equipe.

Glossário de Termos Técnicos

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

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

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.

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

GlorfindelBot: Bot mantido pela Elven, responsável pelo envio das notificações da Elven Platform aos grupos do Telegram.

Identificador do grupo: Número que identifica um grupo no Telegram de forma única. Em grupos, esse número é negativo.

Time (Elven Platform): Agrupamento de usuários responsáveis pelo atendimento de alertas e incidentes. As integrações de canais de comunicação são configuradas no âmbito do time.

Integrations for notifications: Aba do time na Elven Platform em que são registrados os canais de comunicação utilizados para notificação.

Notification Rules: Aba do time na Elven Platform em que se define quais tipos de notificação são direcionados a cada canal configurado.

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

Severity: Label que informa o nível de severidade do evento, permitindo à plataforma classificá-lo e estabelecer prioridade de atendimento.

Not-classified: Estado atribuído ao evento que chega à plataforma sem informação de severidade, no qual não é possível estabelecer prioridade em relação aos demais eventos.

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.

Plantão (On-call): Escala que define quais responsáveis estão disponíveis para atendimento em determinado período.