Alertas e notificações

Como funcionam

Quando um evento relevante acontece, o sistema registra o incidente e dispara o aviso pelos canais habilitados. Ao normalizar, um segundo aviso de problema resolvido sai pelos mesmos canais, informando o tempo decorrido. Os avisos podem sair por até cinco canais:

O que gera alerta

Cada envio fica registrado no histórico de incidentes: a coluna Envio do modal Logs da tela de Dispositivos mostra por quais canais cada alerta saiu (Telegram, e-mail, WhatsApp e push). É o primeiro lugar para verificar quando alguém diz que "não recebeu o alerta". Veja Histórico de incidentes.

Prioridade do canal

Cada canal tem uma configuração de quando alertar. A regra geral vale para Telegram, e-mail, WhatsApp e push (o webhook não tem seletor de prioridade: ativo, recebe tudo dos escopos marcados):

• Offline/Alerta (ou Sensor Offline ou em Alerta, no e-mail): recebe tudo, tanto quedas quanto estouros de limite.
• Offline (ou Sensor Offline): recebe apenas quando o sensor cai.
• Desativado: o canal fica cadastrado mas não recebe nada.

Mensagens personalizáveis

Os textos dos alertas de Dispositivos são modelos editáveis. Na tela de configurações do ambiente Dispositivos existem os quadros Modelo de alerta: PROBLEMA ENCONTRADO e Modelo de alerta: PROBLEMA RESOLVIDO, com título e corpo livres. O corpo aceita a formatação do Telegram (*negrito* e _itálico_) e variáveis que o sistema substitui no envio, como #nome_dispositivo, #nome_grupo, #nome_sensor, #ip, #problema e #data. No modelo de resolvido também existem #solucao, #data_atual e #tempo_decorrido. O botão Restaurar predefinição volta ao texto padrão no idioma do sistema.

Os mesmos modelos valem para todos os canais: quando o canal não suporta a formatação, o sistema adapta o texto automaticamente (o e-mail vira HTML e o push vira texto puro).

Herança de canais

Este é o conceito mais importante da área. Os canais cadastrados na aba Integrações são os destinos padrão do sistema. Cada ambiente (Dispositivos, OLT, Concentradora, Flow) pode usar esses padrões, ter destinos próprios ou não notificar nada. Para Telegram e WhatsApp, o seletor de cada ambiente tem três estados:

O webhook fica de fora dessa cadeia: ele é uma configuração única do sistema, e o que define o que cada webhook recebe são as caixas de escopo (Dispositivos e OLT) do próprio cadastro. Veja Webhook.

Onde configurar em cada ambiente:

Regra de resolução

Para um sensor que pertence a um grupo, a cadeia é resolvida de baixo para cima:

1. Se o grupo customiza, valem os canais do grupo.
2. Se o grupo herda, vale a configuração do ambiente Dispositivos.
3. Se o ambiente herda, valem os padrões da aba Integrações.

Push e permissões

O push do app RAVI Mobile tem um filtro de permissão embutido: o aviso de um alerta de dispositivo só chega aos usuários cujo grupo de usuários tem permissão de ver o grupo de dispositivos do sensor. Na prática, cada técnico só recebe push do que pode enxergar no sistema.

Nível do alerta de ONU (OLT)

Além de ligar e desligar as notificações da OLT, existe o nível do alerta de ONU: alertar apenas ONU offline por perda óptica (rompimento) ou alertar por qualquer motivo, incluindo interrupção de energia detectada. Cada ONU gera um único aviso até normalizar, o que evita enxurrada de mensagens repetidas. Detalhes em OLT: Configurações.

WhatsApp

O canal de WhatsApp usa um número do próprio provedor, pareado por QR Code diretamente no servidor Ravi. Não há nuvem de terceiros: a sessão do número fica no seu servidor.

Ativar e parear

1. Abra Configurações (engrenagem), aba Integrações, quadro do WhatsApp.
2. Selecione Servidor Whatsapp ativo.
3. No celular que vai hospedar o número, abra o WhatsApp, toque em mais opções (ou Configurações) e selecione Aparelhos Conectados.
4. Aponte a câmera para o QR Code exibido na tela. O QR se renova sozinho enquanto a página está aberta.
5. Quando conectar, o QR some e aparece Aparelho conectado com o número, junto dos botões Desconectar e Testar conexão.
6. Clique em Testar conexão para receber uma mensagem de teste e confirmar o funcionamento.

Selecionar quem recebe

Abaixo do pareamento fica a lista Selecione os contatos que deseja enviar alertas, com campo de busca. A lista vem da agenda do número pareado: marque os contatos e grupos que devem receber os avisos. Para um destinatário que não está na agenda, use a linha fixa no topo da lista para adicionar um número manualmente; o sistema valida o número no WhatsApp antes de salvar.

Esse mesmo seletor de contatos aparece nas configurações de Dispositivos, grupos, OLT, Concentradora e Flow quando o ambiente customiza os próprios destinatários.

Quando alertar

O seletor de prioridade do quadro define o comportamento: Offline e Alertas (recebe tudo) ou Alertar apenas quando Offline.

Uso externo do número

O mesmo servidor de WhatsApp pode ser aproveitado para o envio de mensagens externas do provedor (por exemplo, avisos do ERP), por meio da API pública com chave que tenha a permissão de WhatsApp no Gerenciamento de API. Consulte a documentação de API para os detalhes.

Problemas comuns

• QR Code não carrega: o serviço local de WhatsApp do servidor está parado. Acione o suporte ou reinicie o serviço pelo servidor.
• Parou de enviar: a sessão caiu (natureza da integração não oficial). Abra o quadro: se ele voltou a mostrar o QR, pareie novamente e use Testar conexão.
• Contato aparece sem nome ou com dígitos ocultos: limitação de endereçamento do WhatsApp para contatos não sincronizados. Use a linha de adicionar número manualmente.
• Listas grandes atrasam: o envio é sequencial, com intervalo de 1 segundo entre contatos. Prefira grupos ou uma lista enxuta de destinatários.

Telegram

O Telegram é o canal mais flexível: aceita vários destinos (chats ou grupos, cada um com seu bot), janela de horário por destino e prioridade individual. É o canal recomendado como base dos alertas.

Pré-requisito

Crie um bot no Telegram conversando com o @BotFather (ele gera o token do bot) e adicione o bot ao chat ou grupo que vai receber os alertas.

Cadastrar um destino

1. Abra Configurações (engrenagem), aba Integrações, quadro Alertas pelo Telegram.
2. Deixe o seletor em Ativado.
3. Clique em Inserir Telegram e preencha os campos do destino.
4. Se não souber o Chat ID, use o botão Buscar Chat ID (veja abaixo).
5. Salve e clique em Testar no destino recém-criado: o modal Resultado do Teste confirma a entrega.

Buscar Chat ID

O botão Buscar Chat ID abre um assistente que, com o token preenchido, consulta as conversas recentes do bot e lista os chats encontrados (Chat ID, nome e tipo) para você clicar e preencher o campo automaticamente.

Gerenciar destinos

Cada destino cadastrado tem os botões Alterar (abre o modal Gerenciamento de Telegram), Testar e Excluir.

Dicas de operação

• Use as janelas de horário para montar escalas de plantão: um destino do plantão noturno de 22:00 a 06:00 com prioridade Offline, por exemplo.
• A prioridade Desativado serve para pausar um destino temporariamente sem perder o token e o Chat ID.
• Os modelos de mensagem aceitam a formatação do Telegram (*negrito* e _itálico_); caracteres especiais são tratados automaticamente.
• Se o teste passa mas o alerta real não chega, confira a janela de horário do destino e a prioridade (a prioridade Offline ignora alertas de limite).

E-mail

O canal de e-mail usa um servidor SMTP do próprio provedor. É o canal indicado para registro formal dos incidentes e é o único que recebe anexos, como o PDF de post-mortem de ataque do Flow. Novo na 7.2 o envio com anexo.

Configurar

1. Abra Configurações (engrenagem), aba Integrações, quadro Alertas por e-mail.
2. Marque Sim para ativar o canal.
3. Preencha os dados do servidor SMTP e os destinatários (tabela abaixo).
4. Clique em Testar a conexão: o sistema envia um e-mail de teste e exibe o erro do servidor SMTP caso a entrega falhe.
5. Clique em Salvar alterações na barra inferior para os campos passarem a valer.

Boas práticas

• Use uma conta de e-mail dedicada aos alertas, não a conta pessoal de um técnico.
• Como o remetente é o próprio usuário SMTP, confira o SPF e o DKIM do domínio para os alertas não caírem em spam.
• Na maioria dos provedores de e-mail, a combinação porta 587 com SSL/TLS marcado é a que funciona.
• A porta SMTP configurada entra automaticamente nas regras de saída do firewall do servidor: não remova essa regra na aba Firewall.

Anexos e relatórios

Quando um ataque de severidade crítica detectado pelo Flow é encerrado, o e-mail de "Ataque encerrado" chega com o PDF de post-mortem do incidente anexado. Esse comportamento pode ser desligado nas configurações do Flow. Veja Post-mortem automático.

Webhook

Novo na 7.2 O webhook entrega cada alerta em uma URL do seu próprio sistema, como uma requisição POST com corpo em JSON. É o canal para integrar os avisos do Ravi Monitor a um ERP, um painel interno, um sistema de plantão ou qualquer automação que aceite requisições HTTP.

Cadastrar

1. Abra Configurações (engrenagem), aba Integrações, quadro Gerenciar Webhook.
2. Clique em Novo Webhook.
3. Informe a URL do Webhook, começando com http:// ou https://.
4. Clique em Testar: o sistema envia uma mensagem de teste na hora, mesmo antes de salvar, e mostra o resultado logo abaixo do campo.
5. Preencha a Descrição se quiser registrar o propósito (ex.: "Abrir ticket no ERP").
6. Em Escopo de disparo, marque Dispositivos, OLT ou ambos (ao menos um é obrigatório). Concentradora e DNS aparecem como em breve e ainda não podem ser marcados.
7. Deixe Webhook ativo marcado e clique em Criar Webhook.

Cadastre quantos webhooks precisar, cada um com URL e escopo próprios. Na lista do quadro, cada webhook mostra a URL, o selo Ativo ou Inativo, o escopo, a descrição e os botões Alterar e Excluir. Desmarcar Webhook ativo pausa o envio sem perder o cadastro.

O que dispara

O webhook é uma configuração única do sistema: não participa da herança de canais e não tem seletor de prioridade nem janela de horário. Estando ativo, recebe todos os eventos dos escopos marcados.

O que chega na sua URL

Cada evento é um POST com Content-Type: application/json. O corpo sempre traz estes campos:

Nos eventos do escopo Dispositivos vêm também os campos dispositivo (nome) e ip; no evento alerta vem ainda statusAlert, um código numérico do tipo de problema (o texto em mensagem já descreve o problema por extenso). Nos eventos do escopo OLT vem o campo origem_modulo com o valor olt.

{"origem":"ravi-monitor","mensagem":"PROBLEMA ENCONTRADO ...","data":"2026-07-24 14:32:05",
"evento":"alerta","dispositivo":"Roteador Borda","ip":"10.0.0.1","statusAlert":3}

Requisitos e dicas

• A URL precisa responder com um código de sucesso (2xx) em até 10 segundos. Qualquer outra resposta conta como falha, e não há nova tentativa para aquele evento.
• O envio não usa token nem assinatura: qualquer um que conheça a URL consegue enviar um POST parecido. Prefira HTTPS com um endereço difícil de adivinhar e valide o conteúdo no seu sistema.
• Cada webhook é independente dos demais canais: se a URL sair do ar, Telegram, e-mail, WhatsApp e push continuam enviando normalmente.
• Para pausar temporariamente, edite o webhook e desmarque Webhook ativo em vez de excluir.