Sistema de modelos - Conteúdo dinâmico de notificação

Os modelos no Echobell permitem que você crie notificações dinâmicas e ricas em contexto, incorporando variáveis aos títulos e corpos das suas notificações. Esse recurso poderoso possibilita alertas personalizados e informativos que se adaptam aos dados do gatilho, transformando notificações genéricas em informações acionáveis.

Em vez de receber uma mensagem genérica de "Alerta acionado", os modelos permitem criar notificações específicas como "CPU do servidor de produção a 95%" ou "Build #142 falhou na etapa de deploy" - oferecendo contexto imediato sem exigir nenhuma investigação adicional.

Sintaxe básica de modelos

Nos modelos do Echobell, você pode usar variáveis envolvendo-as em chaves duplas:

{{variableName}}

Quando um canal é acionado, essas variáveis são substituídas pelos valores reais passados pelo gatilho. Por exemplo, se o seu modelo de título for You have received ${{amount}} e você acionar o canal com um valor de amount igual a 100, a notificação resultante será exibida como You have received $100.

Expressões avançadas de modelo

Os modelos do Echobell oferecem suporte a diversas expressões para cenários mais complexos:

• Acesso a propriedades de objetos

{{user.name}}
{{data["value"]}}

• Acesso a elementos de array

{{items[0]}}

• Uso de operadores de comparação

{{status == "active"}}
{{age > 18}}

• Operadores lógicos

{{isSubscribed && !isPaused}}
{{isUrgent || isHighPriority}}

Todos os operadores padrão são suportados: ==, !=, <, >, <=, >=, &&, || e !.

Variáveis de modelo em diferentes gatilhos

Gatilhos por webhook

Ao acionar via webhook, você pode fornecer variáveis por meio de:

1. Parâmetros de query string:

   GET https://hook.echobell.one/t/<channel-token>?amount=100&status=complete

2. Corpo JSON (para requisições POST):

   POST https://hook.echobell.one/t/<channel-token>
   Content-Type: application/json
   
   {
     "amount": 100,
     "status": "complete",
     "user": {
       "name": "John",
       "id": 12345
     }
   }

3. Variáveis especiais:

   • externalLink: fornece um link clicável nos registros de notificação
   • bodyAsText: o conteúdo em texto simples do corpo da requisição, se o Content-Type for text/plain
   • header: dá acesso aos cabeçalhos da requisição HTTP (por exemplo, {{header["content-type"]}})

Gatilhos por e-mail

Quando um canal é acionado por e-mail, as seguintes variáveis ficam disponíveis automaticamente:

• from: o endereço de e-mail do remetente
• to: o endereço de e-mail do destinatário
• subject: a linha de assunto do e-mail
• text: o conteúdo em texto simples do e-mail
• html: o conteúdo HTML do e-mail

Casos de uso dos modelos

Comparações e booleanos

Expressões que usam operadores de comparação ou lógicos renderizam seu resultado booleano como o texto true ou false:

Payment over $1000: {{amount > 1000}}
High priority: {{isUrgent || isImportant}}

Os modelos do Echobell não oferecem suporte a lógica if/else em linha (ternária). Para enviar conteúdos diferentes em situações diferentes, use as Condições do canal para rotear os gatilhos ou interpole os valores brutos diretamente.

Condições do canal

Além de usar modelos no conteúdo das notificações, você pode definir Condições nas configurações avançadas do canal, que determinam se as notificações devem ser enviadas. Essas condições usam a mesma sintaxe de expressões (sem as chaves).

Por exemplo, para enviar notificações apenas para valores acima de um limite:

amount > 100

Modelos de link

Configure um modelo de link personalizado nas configurações avançadas do canal para criar links clicáveis nos registros de notificação:

https://dashboard.example.com/orders/{{orderId}}

Se nenhum modelo de link for definido, o valor da variável externalLink será usado por padrão.

Variáveis de tempo do sistema (UTC)

Essas variáveis estão sempre disponíveis para os modelos (e para as condições) e são calculadas em UTC.

Os valores a seguir são injetados diretamente (de forma plana) e podem ser usados pelo nome:

• year, month (1–12)
• dayOfMonth, dayOfWeek (0–6, domingo = 0)
• hour (0–23), minute, second
• date (YYYY-MM-DD), time (HH:mm:ss)
• iso: carimbo de data/hora ISO‑8601 (por exemplo, 2025-05-06T12:34:56.789Z)

Outros valores estão disponíveis apenas no namespace sys. (eles não são injetados como nomes planos):

• sys.timezone: sempre "UTC"
• sys.now: carimbo de data/hora ISO‑8601 (mesmo valor de iso)
• sys.epochMs, sys.epochSeconds: tempo atual desde a época Unix (número)
• sys.monthName: nome do mês (January–December)
• sys.dayOfWeekName: nome do dia (Sunday–Saturday)

O namespace sys. também espelha todos os valores planos (por exemplo, sys.year, sys.hour).

Exemplos:

Sent at {{date}} {{time}} {{sys.timezone}}
Today is {{sys.dayOfWeekName}}, {{sys.monthName}} {{dayOfMonth}}, {{year}}
Epoch: {{sys.epochSeconds}}

Boas práticas

Lide com variáveis ausentes

O Echobell não tem operador de valor padrão. O operador || é puramente lógico — ele avalia os dois lados como booleanos e renderiza true ou false. Ou seja, {{username || "Anonymous User"}} renderiza o texto literal true ou false, nunca o nome de usuário nem o texto alternativo.

Quando uma variável está ausente, {{variable}} é simplesmente renderizada como uma string vazia. Elabore seus rótulos de modo que um valor vazio continue legível:

User: {{username}}
Server: {{serverName}}
Errors detected: {{errorCount}}

Se você precisa de um valor garantido, envie-o explicitamente no payload do gatilho, em vez de depender de um valor alternativo no modelo.

Modelos informativos

Inclua as informações essenciais nos seus modelos para tornar as notificações acionáveis sem exigir contexto adicional:

Bons exemplos:

Title: {{service}} {{status}} on {{environment}}
Body: {{errorMessage}} at {{timestamp}}
Action required: {{recommendedAction}}

Evite:

Title: Alert
Body: Check logs

Mantenha os modelos concisos

As notificações são exibidas melhor quando títulos e corpos são claros e diretos:

• Títulos: 3-8 palavras é o ideal, no máximo 20 palavras
• Corpos: 1-3 frases é o ideal, evite blocos enormes de texto
• Prioridade: coloque a informação mais importante primeiro

Restrições das notificações no iOS:

• Título: cerca de 40 caracteres visíveis na visualização recolhida
• Corpo: cerca de 60 caracteres na visualização recolhida, mais quando expandida

Use nomes consistentes

Mantenha uma nomenclatura de variáveis consistente entre os seus canais:

• Use nomes claros e descritivos: server_name, não sn
• Siga uma convenção: snake_case, camelCase ou kebab-case
• Seja consistente entre canais relacionados
• Documente as variáveis esperadas para o seu time

Teste com rigor

Teste seus modelos com diferentes combinações de variáveis para garantir que sejam renderizados como esperado:

1. Teste com todas as variáveis presentes
2. Teste com variáveis opcionais ausentes
3. Teste com caracteres especiais e Unicode
4. Teste com valores muito longos
5. Teste com strings vazias
6. Teste com números, booleanos, arrays e objetos

Estruture para facilitar a leitura

Use formatação para deixar o conteúdo da notificação fácil de ler rapidamente:

🚨 Alert: {{alertName}}
━━━━━━━━━━━━━━━
Server: {{server}}
Metric: {{metric}}  
Value: {{value}}
Time: {{time}}
━━━━━━━━━━━━━━━
Details: {{message}}

Ou use rótulos simples:

Server: {{server}}
CPU Usage: {{cpu}}%
Memory: {{memory}}%
Status: {{status}}

Aproveite as expressões

Use expressões para expor valores calculados e resultados de comparações:

Title: {{service}} alert — critical: {{severity == "critical"}}
Body: {{metric}} is {{value}} (over threshold: {{value > threshold}})

Expressões de comparação e lógicas são renderizadas como true ou false; combine-as com rótulos de texto estáticos para dar sentido ao resultado.

Considere os fusos horários

Lembre-se de que as variáveis de tempo do sistema estão em UTC. Documente isso ou faça a conversão nos seus modelos:

Alert triggered at {{time}} UTC
Triggered: {{date}} {{time}} (UTC)

Padrões e exemplos comuns

Monitoramento de servidores

Title: {{hostname}} - {{metric}} Alert
Body: {{metric}} on {{hostname}} is at {{value}}{{unit}}
Threshold: {{threshold}}{{unit}}
Time: {{date}} {{time}}

Pipelines de CI/CD

Title: {{repository}} - Build {{status}}
Body: Build #{{buildNumber}} {{status}} in {{duration}}s
Branch: {{branch}}
Commit: {{commit_message}}
Author: {{author}}

E-commerce

Title: New Order #{{orderNumber}}
Body: Customer: {{customerName}}
Items: {{itemCount}} items
Total: ${{totalAmount}}
Shipping: {{shippingAddress}}

Rastreamento de erros

Title: {{errorType}} in {{service}}
Body: {{errorMessage}}
File: {{filename}}:{{lineNumber}}
User: {{userId}}
Environment: {{environment}}

Recursos avançados

Modelos de link

Configure um modelo de link personalizado nas configurações avançadas do canal para criar links clicáveis nos registros de notificação:

https://dashboard.example.com/orders/{{orderId}}
https://grafana.example.com/d/{{dashboardId}}
https://github.com/{{repo}}/actions/runs/{{runId}}

Se nenhum modelo de link for definido, o valor da variável externalLink será usado por padrão. Isso é útil para dar acesso rápido a dashboards, logs ou documentação relevantes diretamente pela notificação.

Exibindo valores calculados

Os modelos não podem criar ramificações com lógica ternária (? :) e não existe operador de concatenação de strings (+). Em vez disso, interpole valores e resultados de comparação diretamente, usando texto estático como rótulo:

Online: {{isOnline}}
High severity: {{severity > 5}}
Errors detected: {{count}}

Expressões de comparação são renderizadas como true ou false. Para enviar mensagens realmente diferentes em cada situação, roteie os gatilhos com as Condições do canal, em vez de criar ramificações dentro de um único modelo.

Condições do canal

Além de usar modelos no conteúdo das notificações, você pode definir Condições nas configurações avançadas do canal, que determinam se as notificações devem ser enviadas. Essas condições usam a mesma sintaxe de expressões (sem as chaves).

Por exemplo, para enviar notificações apenas para valores acima de um limite:

amount > 100
status == "critical"
temperature > 30 && location == "datacenter"

Isso evita a fadiga de alertas, filtrando eventos não críticos antes que as notificações sejam enviadas. Saiba mais no nosso guia de Condições.

Documentação relacionada

• Integração com webhook - Saiba como passar variáveis por webhooks
• Gatilhos por e-mail - Variáveis disponíveis nos gatilhos por e-mail
• Condições - Filtre notificações com expressões condicionais
• Primeiros passos - Configure seu primeiro canal com modelos

Solução de problemas

O modelo não está renderizando as variáveis:

• Verifique se os nomes das variáveis coincidem exatamente (diferenciam maiúsculas de minúsculas)
• Confirme se as variáveis estão sendo enviadas no gatilho por webhook/e-mail
• Teste primeiro com variáveis simples e só depois aumente a complexidade

Variáveis aparecendo vazias:

• Confirme se a variável existe nos dados do gatilho
• Verifique se há erros de digitação nos nomes das variáveis
• Confira a estrutura do JSON para propriedades aninhadas

Erros de expressão:

• Valide a sintaxe primeiro com expressões simples
• Certifique-se de que os operadores estão devidamente espaçados
• Verifique se o acesso às propriedades usa a sintaxe correta

Precisa de ajuda? Acesse nossa Central de Suporte ou entre em contato pelo e-mail echobell@weelone.com.

---

Os modelos são uma forma poderosa de criar notificações dinâmicas e informativas que dão aos usuários exatamente a informação de que precisam, quando precisam. Comece com a substituição simples de variáveis e vá adicionando gradualmente expressões e lógica condicional para criar sistemas de notificação sofisticados.