Echobell
App Store Google Play

템플릿 시스템 - 동적 알림 콘텐츠

변수, 표현식, 시스템 값을 활용해 동적 알림 템플릿을 만드는 방법과 명확한 알림 메시지를 위한 모범 사례를 알아봅니다.

Echobell의 템플릿을 사용하면 알림 제목과 본문에 변수를 넣어 상황 정보가 풍부한 동적 알림을 만들 수 있습니다. 이 강력한 기능을 활용하면 트리거 데이터에 따라 내용이 달라지는 맞춤형 알림을 받을 수 있으며, 밋밋한 알림이 바로 대응 가능한 정보로 바뀝니다.

"Alert triggered" 같은 뻔한 메시지를 받는 대신, 템플릿으로는 "프로덕션 서버 CPU 사용률 95%"나 "빌드 #142가 배포 단계에서 실패"처럼 구체적인 알림을 만들 수 있습니다. 따로 확인하지 않아도 상황을 즉시 파악할 수 있습니다.

기본 템플릿 문법

Echobell 템플릿에서는 변수를 이중 중괄호로 감싸서 사용할 수 있습니다:

{{variableName}}

채널이 트리거되면 이 변수들은 트리거를 통해 전달된 실제 값으로 대체됩니다. 예를 들어 제목 템플릿이 You have received ${{amount}}이고 amount 값을 100으로 하여 채널을 트리거하면, 알림은 You have received $100으로 표시됩니다.

고급 템플릿 표현식

Echobell 템플릿은 더 복잡한 상황을 위해 다양한 표현식을 지원합니다:

  • 객체 속성 접근
{{user.name}}
{{data["value"]}}
  • 배열 요소 접근
{{items[0]}}
  • 비교 연산자 사용
{{status == "active"}}
{{age > 18}}
  • 논리 연산자
{{isSubscribed && !isPaused}}
{{isUrgent || isHighPriority}}

표준 연산자는 모두 지원됩니다: ==, !=, <, >, <=, >=, &&, ||, !.

트리거 종류별 템플릿 변수

Webhook 트리거

Webhook으로 트리거할 때는 다음과 같은 방법으로 변수를 전달할 수 있습니다:

  1. 쿼리 문자열 파라미터:

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

  2. JSON 본문 (POST 요청의 경우):

    POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "amount": 100,
  "status": "complete",
  "user": {
    "name": "John",
    "id": 12345
  }
}

  3. 특수 변수:

    • externalLink: 알림 기록에서 클릭할 수 있는 링크를 제공합니다
    • bodyAsText: Content-Type이 text/plain인 경우 요청 본문의 일반 텍스트 내용입니다
    • header: HTTP 요청 헤더에 접근할 수 있습니다 (예: {{header["content-type"]}})

이메일 트리거

채널이 이메일로 트리거되면 다음 변수를 자동으로 사용할 수 있습니다:

  • from: 보낸 사람의 이메일 주소
  • to: 받는 사람의 이메일 주소
  • subject: 이메일 제목
  • text: 이메일의 일반 텍스트 내용
  • html: 이메일의 HTML 내용

템플릿 활용 사례

비교와 불리언

비교 연산자나 논리 연산자를 사용하는 표현식은 불리언 결과를 true 또는 false라는 텍스트로 렌더링합니다:

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

Echobell 템플릿은 인라인 if/else(삼항) 로직을 지원하지 않습니다. 상황에 따라 다른 내용을 보내려면 채널 조건으로 트리거를 분기하거나, 원본 값을 그대로 삽입하십시오.

채널 조건

알림 내용에 템플릿을 사용하는 것 외에도, 채널 고급 설정에서 알림을 보낼지 말지를 결정하는 조건을 설정할 수 있습니다. 이 조건은 중괄호 없이 동일한 표현식 문법을 사용합니다.

예를 들어 특정 임계값을 넘는 금액에 대해서만 알림을 보내려면 다음과 같이 작성합니다:

amount > 100

링크 템플릿

알림 기록에서 클릭할 수 있는 링크를 만들려면 채널 고급 설정에서 사용자 지정 링크 템플릿을 구성하십시오:

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

링크 템플릿을 설정하지 않으면 기본적으로 externalLink 변수의 값이 사용됩니다.

시스템 시간 변수 (UTC)

이 변수들은 템플릿(및 조건)에서 항상 사용할 수 있으며 UTC 기준으로 계산됩니다.

다음 값들은 평면 구조로 직접 주입되므로 이름만으로 사용할 수 있습니다:

  • year, month (1–12)
  • dayOfMonth, dayOfWeek (0–6, 일요일 = 0)
  • hour (0–23), minute, second
  • date (YYYY-MM-DD), time (HH:mm:ss)
  • iso: ISO‑8601 타임스탬프 (예: 2025-05-06T12:34:56.789Z)

그 밖의 값들은 sys. 네임스페이스에서만 사용할 수 있습니다(평면 이름으로는 주입되지 않습니다):

  • sys.timezone: 항상 "UTC"
  • sys.now: ISO‑8601 타임스탬프(iso와 같은 값)
  • sys.epochMs, sys.epochSeconds: Unix 에포크 이후 경과한 현재 시각(숫자)
  • sys.monthName: 월 이름 (January–December)
  • sys.dayOfWeekName: 요일 이름 (Sunday–Saturday)

sys. 네임스페이스에는 모든 평면 값도 그대로 들어 있습니다(예: sys.year, sys.hour).

예시:

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

모범 사례

누락된 변수 처리하기

Echobell에는 기본값 연산자가 없습니다. || 연산자는 순수한 논리 연산자로, 양쪽을 불리언으로 평가해 true 또는 false를 렌더링합니다. 따라서 {{username || "Anonymous User"}}는 사용자 이름이나 대체 문자열이 아니라 true 또는 false라는 문자 그대로의 텍스트를 렌더링합니다.

변수가 없으면 {{variable}}은 그냥 빈 문자열로 렌더링됩니다. 값이 비어 있어도 내용이 명확하게 읽히도록 레이블을 설계하십시오:

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

값이 반드시 필요하다면 템플릿의 대체 값에 의존하지 말고 트리거 페이로드에 명시적으로 담아 보내십시오.

정보가 담긴 템플릿

추가 설명 없이도 바로 대응할 수 있도록 템플릿에 핵심 정보를 담으십시오:

좋은 예:

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

피해야 할 예:

Title: Alert
Body: Check logs

템플릿을 간결하게 유지하기

알림은 제목과 본문이 명확하고 요점만 담고 있을 때 가장 잘 표시됩니다:

  • 제목: 3~8단어가 이상적이며 최대 20단어
  • 본문: 1~3문장이 이상적이며 긴 글은 피하기
  • 우선순위: 가장 중요한 정보를 앞에 배치

iOS 알림의 제약:

  • 제목: 접힌 상태에서 약 40자까지 표시
  • 본문: 접힌 상태에서 약 60자, 펼치면 더 많이 표시

일관된 이름 사용하기

여러 채널에서 변수 이름을 일관되게 유지하십시오:

  • 명확하고 설명적인 이름 사용: sn이 아니라 server_name
  • 하나의 규칙 준수: snake_case, camelCase 또는 kebab-case
  • 관련된 채널 사이에서 일관성 유지
  • 팀원을 위해 필요한 변수를 문서화

꼼꼼하게 테스트하기

템플릿이 의도한 대로 렌더링되는지 다양한 변수 조합으로 테스트하십시오:

  1. 모든 변수가 있는 경우 테스트
  2. 선택적 변수가 없는 경우 테스트
  3. 특수 문자와 유니코드로 테스트
  4. 매우 긴 값으로 테스트
  5. 빈 문자열로 테스트
  6. 숫자, 불리언, 배열, 객체로 테스트

읽기 쉽게 구성하기

알림 내용을 한눈에 훑어볼 수 있도록 서식을 활용하십시오:

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

또는 간단한 레이블을 사용하십시오:

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

표현식 활용하기

표현식을 사용해 계산된 값과 비교 결과를 드러내십시오:

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

비교 표현식과 논리 표현식은 true 또는 false로 렌더링되므로, 고정된 레이블 텍스트와 함께 사용해 의미를 전달하십시오.

시간대 고려하기

시스템 시간 변수는 UTC 기준이라는 점을 기억하십시오. 이를 문서에 밝히거나 템플릿에서 변환하십시오:

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

자주 쓰이는 패턴과 예시

서버 모니터링

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

CI/CD 파이프라인

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

이커머스

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

오류 추적

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

고급 기능

링크 템플릿

알림 기록에서 클릭할 수 있는 링크를 만들려면 채널 고급 설정에서 사용자 지정 링크 템플릿을 구성하십시오:

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

링크 템플릿을 설정하지 않으면 기본적으로 externalLink 변수의 값이 사용됩니다. 알림에서 곧바로 관련 대시보드, 로그, 문서로 이동할 수 있어 유용합니다.

계산된 값 표시하기

템플릿은 삼항(? :) 로직으로 분기할 수 없고, 문자열 연결 연산자(+)도 없습니다. 대신 값과 비교 결과를 그대로 삽입하고 레이블에는 고정된 텍스트를 사용하십시오:

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

비교 표현식은 true 또는 false로 렌더링됩니다. 상황마다 실제로 다른 메시지를 보내려면 하나의 템플릿 안에서 분기하지 말고 채널 조건으로 트리거를 분기하십시오.

채널 조건

알림 내용에 템플릿을 사용하는 것 외에도, 채널 고급 설정에서 알림을 보낼지 말지를 결정하는 **조건**을 설정할 수 있습니다. 이 조건은 중괄호 없이 동일한 표현식 문법을 사용합니다.

예를 들어 특정 임계값을 넘는 금액에 대해서만 알림을 보내려면 다음과 같이 작성합니다:

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

이렇게 하면 중요하지 않은 이벤트를 알림 전에 걸러내어 알림 피로를 막을 수 있습니다. 자세한 내용은 조건 가이드에서 확인하십시오.

관련 문서

문제 해결

템플릿이 변수를 렌더링하지 않는 경우:

  • 변수 이름이 정확히 일치하는지 확인하십시오(대소문자 구분)
  • Webhook/이메일 트리거에서 변수가 전달되고 있는지 확인하십시오
  • 먼저 간단한 변수로 테스트한 뒤 점차 복잡하게 만들어 보십시오

변수가 빈 값으로 표시되는 경우:

  • 트리거 데이터에 해당 변수가 있는지 확인하십시오
  • 변수 이름에 오타가 없는지 확인하십시오
  • 중첩된 속성의 JSON 구조를 확인하십시오

표현식 오류:

  • 먼저 간단한 표현식으로 문법을 검증하십시오
  • 연산자 앞뒤 간격이 올바른지 확인하십시오
  • 속성 접근에 올바른 문법을 사용했는지 확인하십시오

도움이 필요하십니까? 지원 센터를 방문하시거나 echobell@weelone.com으로 문의해 주십시오.

템플릿은 사용자가 필요한 정보를 필요한 순간에 정확히 받아 볼 수 있도록 동적이고 유익한 알림을 만드는 강력한 방법입니다. 간단한 변수 치환에서 시작해 표현식과 조건 로직을 차근차근 더해 가면서 정교한 알림 시스템을 만들어 보십시오.