--- title: 템플릿 시스템 - 동적 알림 콘텐츠 sidebarTitle: 템플릿 description: 변수, 표현식, 시스템 값을 활용해 동적 알림 템플릿을 만드는 방법과 명확한 알림 메시지를 위한 모범 사례를 알아봅니다. --- # Echobell의 템플릿 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. **쿼리 문자열 파라미터**: ```http GET https://hook.echobell.one/t/?amount=100&status=complete ``` 2. **JSON 본문** (POST 요청의 경우): ```http POST https://hook.echobell.one/t/ 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(삼항) 로직을 지원하지 **않습니다**. 상황에 따라 다른 내용을 보내려면 채널 [조건](/docs/conditions)으로 트리거를 분기하거나, 원본 값을 그대로 삽입하십시오. ### 채널 조건 알림 내용에 템플릿을 사용하는 것 외에도, 채널 고급 설정에서 알림을 보낼지 말지를 결정하는 **조건**을 설정할 수 있습니다. 이 조건은 중괄호 없이 동일한 표현식 문법을 사용합니다. 예를 들어 특정 임계값을 넘는 금액에 대해서만 알림을 보내려면 다음과 같이 작성합니다: ``` 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`로 렌더링됩니다. 상황마다 실제로 다른 메시지를 보내려면 하나의 템플릿 안에서 분기하지 말고 채널 [조건](/docs/conditions)으로 트리거를 분기하십시오. ### 채널 조건 알림 내용에 템플릿을 사용하는 것 외에도, 채널 고급 설정에서 알림을 보낼지 말지를 결정하는 **[조건](/docs/conditions)**을 설정할 수 있습니다. 이 조건은 중괄호 없이 동일한 표현식 문법을 사용합니다. 예를 들어 특정 임계값을 넘는 금액에 대해서만 알림을 보내려면 다음과 같이 작성합니다: ``` amount > 100 status == "critical" temperature > 30 && location == "datacenter" ``` 이렇게 하면 중요하지 않은 이벤트를 알림 전에 걸러내어 알림 피로를 막을 수 있습니다. 자세한 내용은 [조건 가이드](/docs/conditions)에서 확인하십시오. ## 관련 문서 - **[Webhook 연동](/docs/webhook)** - Webhook으로 변수를 전달하는 방법 알아보기 - **[이메일 트리거](/docs/email-trigger)** - 이메일 트리거에서 사용할 수 있는 변수 - **[조건](/docs/conditions)** - 조건식으로 알림 필터링하기 - **[시작하기](/docs)** - 템플릿으로 첫 채널 설정하기 ## 문제 해결 **템플릿이 변수를 렌더링하지 않는 경우:** - 변수 이름이 정확히 일치하는지 확인하십시오(대소문자 구분) - Webhook/이메일 트리거에서 변수가 전달되고 있는지 확인하십시오 - 먼저 간단한 변수로 테스트한 뒤 점차 복잡하게 만들어 보십시오 **변수가 빈 값으로 표시되는 경우:** - 트리거 데이터에 해당 변수가 있는지 확인하십시오 - 변수 이름에 오타가 없는지 확인하십시오 - 중첩된 속성의 JSON 구조를 확인하십시오 **표현식 오류:** - 먼저 간단한 표현식으로 문법을 검증하십시오 - 연산자 앞뒤 간격이 올바른지 확인하십시오 - 속성 접근에 올바른 문법을 사용했는지 확인하십시오 도움이 필요하십니까? [지원 센터](/docs/support)를 방문하시거나 echobell@weelone.com으로 문의해 주십시오. --- 템플릿은 사용자가 필요한 정보를 필요한 순간에 정확히 받아 볼 수 있도록 동적이고 유익한 알림을 만드는 강력한 방법입니다. 간단한 변수 치환에서 시작해 표현식과 조건 로직을 차근차근 더해 가면서 정교한 알림 시스템을 만들어 보십시오.