---
title: "Home Assistant 연동 - 스마트 홈 알림"
sidebarTitle: Home Assistant
description: "Home Assistant를 Echobell에 연결해 즉각적인 스마트 홈 알림을 받으세요. 보안, 움직임, 온도, 자동화 이벤트를 푸시 알림이나 전화 알림으로 전달합니다."
---

import { Step, Steps } from "fumadocs-ui/components/steps";

# Home Assistant 연동

[Home Assistant](https://www.home-assistant.io/)는 로컬 제어와 프라이버시를 최우선으로 하는 강력한 오픈 소스 홈 오토메이션 플랫폼입니다. Echobell을 Home Assistant와 연동하면 스마트 홈에서 중요한 이벤트가 발생할 때 즉시 알림은 물론 전화 알림까지 받을 수 있습니다. 보안 경보든, 온도 임계값 초과든, 자동화 트리거든 모두 마찬가지입니다.

이 가이드에서는 Webhook 또는 RESTful Notify 서비스를 사용해 Home Assistant 자동화로부터 알림을 받도록 Echobell을 설정하는 방법을 안내합니다.

## 사전 준비 사항

시작하기 전에 다음을 준비했는지 확인하세요.

- 모바일 기기에 설치된 [Echobell 앱](https://apps.apple.com/app/apple-store/id6743597198?pt=128151925&ct=docs-developer-home-assistant-ko&mt=8) / [Google Play](https://play.google.com/store/apps/details?id=one.echobell.echobellandroid)
- 활성화된 Echobell 채널(아직 없다면 앱에서 하나 만드세요)
- 실행 중인 Home Assistant 인스턴스(버전 2023.1 이상 권장)
- Home Assistant 구성에 대한 접근 권한

## 방법 1: Webhook 트리거 사용(권장)

Webhook 방식은 가장 유연한 방법으로, 사용자 지정 데이터를 전송하고 알림에서 [템플릿 변수](/docs/template)를 사용할 수 있습니다.

<Steps>
<Step>
### Echobell Webhook URL 가져오기

1. Echobell 앱을 열고 채널로 이동합니다
2. 채널을 탭해 상세 정보를 확인합니다
3. Triggers 섹션에서 **Webhook URL**을 찾습니다
4. URL을 복사합니다. 다음과 같은 형태입니다: `https://hook.echobell.one/t/<channel-token>`
</Step>
<Step>

### Home Assistant 자동화 만들기

Home Assistant에서는 `rest_command` 서비스를 사용해 Echobell 알림을 실행할 수 있습니다. 먼저 `configuration.yaml`에 REST 명령을 추가합니다:

```yaml
rest_command:
  echobell_notify:
    url: "https://hook.echobell.one/t/<channel-token>"
    method: POST
    content_type: "application/json"
    payload: '{"title": "{{ title }}", "message": "{{ message }}"}'
```

`YOUR_TOKEN`을 실제 Echobell Webhook 토큰으로 바꾸세요.

추가한 뒤에는 새 구성을 불러오도록 Home Assistant를 재시작하세요.

</Step>
<Step>
### 자동화에서 사용하기

이제 어떤 자동화에서든 이 서비스를 호출할 수 있습니다. 다음은 문이 열렸을 때 알림을 보내는 예시입니다:

```yaml
automation:
  - alias: "Door Open Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door
        to: "on"
    action:
      - service: rest_command.echobell_notify
        data:
          title: "Security Alert"
          message: "Front door opened at {{ now().strftime('%H:%M') }}"
```

</Step>
<Step>
### 알림 템플릿 구성하기

Echobell 채널 설정에서 Webhook 데이터를 표시하도록 알림 템플릿을 구성합니다:

- **제목 템플릿**: `{{title}}`
- **본문 템플릿**: `{{message}}`

이제 자동화가 실행되면 사용자 지정 제목과 메시지가 담긴 알림을 받게 됩니다.

</Step>
</Steps>

## 방법 2: RESTful Notify 플랫폼 사용

더 긴밀하게 통합된 방식을 원한다면 Echobell을 Home Assistant의 notify 서비스로 설정할 수 있습니다.

### 구성

`configuration.yaml`에 다음을 추가합니다:

```yaml
notify:
  - name: echobell
    platform: rest
    resource: https://hook.echobell.one/t/<channel-token>
    method: POST_JSON
    data:
      title: "{{ title }}"
      message: "{{ message }}"
```

`YOUR_TOKEN`을 Echobell Webhook 토큰으로 바꾼 다음 Home Assistant를 재시작하세요.

### Notify 서비스 사용하기

이제 다른 notify 서비스와 똑같이 Echobell을 사용할 수 있습니다:

```yaml
automation:
  - alias: "Low Battery Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.phone_battery
        below: 20
    action:
      - service: notify.echobell
        data:
          title: "Low Battery Warning"
          message: "Phone battery is at {{ states('sensor.phone_battery') }}%"
```

## 고급 활용 사례

### 긴급 경보를 활용한 온도 모니터링

[알림 유형](/docs/notification)을 사용해 중요한 온도 경보를 전화 알림으로 보낼 수 있습니다:

```yaml
rest_command:
  echobell_critical:
    url: "https://hook.echobell.one/t/<channel-token>"
    method: POST
    content_type: "application/json"
    payload: '{"temperature": "{{ temperature }}", "location": "{{ location }}", "severity": "critical"}'
```

Echobell 채널에서 [알림 유형](/docs/notification)을 "전화"로 설정하고 다음 템플릿을 사용하세요:

- **제목**: `Critical Temperature Alert`
- **본문**: `{{location}} temperature is {{temperature}}°C - Immediate attention required!`

### 보안 시스템 연동

종합적인 보안 모니터링을 설정합니다:

```yaml
automation:
  - alias: "Security Breach Detection"
    trigger:
      - platform: state
        entity_id:
          - binary_sensor.motion_detector_1
          - binary_sensor.motion_detector_2
          - binary_sensor.window_sensor
        to: "on"
    condition:
      - condition: state
        entity_id: alarm_control_panel.home_alarm
        state: "armed_away"
    action:
      - service: rest_command.echobell_notify
        data:
          title: "🚨 Security Alert"
          message: "{{ trigger.to_state.attributes.friendly_name }} detected activity while system armed"
          sensor: "{{ trigger.entity_id }}"
          timestamp: "{{ now().isoformat() }}"
```

### 스마트 가전 알림

가전 기기의 작동 사이클을 모니터링하고 완료되면 알림을 받습니다:

```yaml
automation:
  - alias: "Washing Machine Complete"
    trigger:
      - platform: state
        entity_id: sensor.washing_machine_power
        to: "0"
        for:
          minutes: 3
    action:
      - service: notify.echobell
        data:
          title: "Washing Machine Done"
          message: "Your laundry is ready to be moved to the dryer"
```

### 환경 모니터링

공기 질, 습도를 비롯한 여러 환경 요소를 추적합니다:

```yaml
automation:
  - alias: "High CO2 Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.living_room_co2
        above: 1000
    action:
      - service: rest_command.echobell_notify
        data:
          title: "Air Quality Warning"
          message: "CO2 level in living room is {{ states('sensor.living_room_co2') }} ppm. Consider ventilating."
```

## 조건을 활용한 스마트 필터링

[Echobell 조건](/docs/conditions)을 사용하면 특정 기준에 따라 알림을 필터링할 수 있습니다. 예를 들어 특정 시간대에만 알리거나 값이 임계값을 넘었을 때만 알릴 수 있습니다:

Echobell 채널에 다음과 같이 조건을 설정합니다:

```
severity == "critical" || (hour >= 22 || hour <= 7)
```

이 조건은 심각도가 critical이거나 야간(오후 10시부터 오전 7시까지)일 때만 알림을 보냅니다.

Home Assistant 자동화에서는 해당 데이터를 함께 전달합니다:

```yaml
action:
  - service: rest_command.echobell_notify
    data:
      title: "Temperature Alert"
      message: "Freezer temperature: {{ states('sensor.freezer_temp') }}°C"
      severity: "{% if states('sensor.freezer_temp') | float > -10 %}critical{% else %}normal{% endif %}"
      hour: "{{ now().hour }}"
```

## 센서 데이터 전송

Home Assistant의 어떤 센서 데이터든 Echobell 알림으로 전달할 수 있습니다:

```yaml
rest_command:
  echobell_sensor_update:
    url: "https://hook.echobell.one/t/<channel-token>"
    method: POST
    content_type: "application/json"
    payload: >
      {
        "sensor_name": "{{ sensor_name }}",
        "current_value": "{{ current_value }}",
        "unit": "{{ unit }}",
        "state": "{{ state }}",
        "timestamp": "{{ timestamp }}"
      }
```

## HTTP 헤더 처리

Echobell은 Webhook 요청의 HTTP 헤더에 접근할 수 있습니다. 인증이나 추적 용도로 유용합니다:

```yaml
rest_command:
  echobell_with_headers:
    url: "https://hook.echobell.one/t/<channel-token>"
    method: POST
    headers:
      X-Home-Assistant-Instance: "{{ instance_name }}"
      X-Automation-ID: "{{ automation_id }}"
    content_type: "application/json"
    payload: '{"message": "{{ message }}"}'
```

Echobell 템플릿에서는 다음과 같이 헤더에 접근합니다:

```
{{header["x-home-assistant-instance"]}}
```

## 디버깅과 테스트

### Webhook 테스트하기

Home Assistant의 개발자 도구 → 서비스에서 구성을 테스트해 보세요:

1. `rest_command.echobell_notify`를 선택합니다
2. 테스트 데이터를 입력합니다:

```yaml
title: "Test Notification"
message: "This is a test from Home Assistant"
```

3. "서비스 호출"을 클릭합니다
4. Echobell 앱에서 알림이 도착했는지 확인합니다

### Home Assistant 로그 확인

알림이 도착하지 않는다면 Home Assistant 로그를 확인하세요:

```bash
# In Home Assistant, go to:
Settings → System → Logs

# Or check the log file:
config/home-assistant.log
```

`rest_command` 관련 오류나 `hook.echobell.one`으로 보낸 HTTP 요청 오류가 있는지 살펴보세요.

### Webhook URL 확인

Webhook URL이 올바른지 확인하세요:

- `https://hook.echobell.one/t/`로 시작해야 합니다
- 토큰이 포함되어 있어야 합니다
- 불필요한 공백이나 문자가 없어야 합니다

## 성능 고려 사항

### 요청 속도 제한

Echobell Webhook에는 남용을 막기 위한 요청 속도 제한이 적용됩니다. 값이 자주 바뀌는 센서라면 다음을 참고하세요:

- 센서 값이 갱신될 때마다 실행되지 않도록 합니다
- 트리거에 `for`를 사용해 디바운스를 적용합니다:

```yaml
trigger:
  - platform: numeric_state
    entity_id: sensor.temperature
    above: 30
    for:
      minutes: 5 # Only trigger after 5 minutes above threshold
```

### 업데이트 묶어 보내기

서로 관련된 이벤트가 여러 개라면 하나의 알림으로 묶어 보내는 방법을 고려하세요:

```yaml
automation:
  - alias: "Daily Home Summary"
    trigger:
      - platform: time
        at: "09:00:00"
    action:
      - service: rest_command.echobell_notify
        data:
          title: "Morning Home Summary"
          message: >
            Temperature: {{ states('sensor.temperature') }}°C
            Humidity: {{ states('sensor.humidity') }}%
            Energy today: {{ states('sensor.daily_energy') }} kWh
            Windows open: {{ expand(states.binary_sensor) | selectattr('state', 'eq', 'on') | selectattr('attributes.device_class', 'eq', 'window') | list | count }}
```

## 보안 모범 사례

### Webhook URL 보호하기

- Webhook URL을 공개 저장소에 커밋하지 마세요
- 민감한 데이터에는 Home Assistant의 secrets를 사용하세요
- Webhook 토큰을 주기적으로 교체하세요

`configuration.yaml`에서 secrets를 사용하는 방법:

```yaml
# secrets.yaml
echobell_webhook: "https://hook.echobell.one/t/<channel-token>"

# configuration.yaml
rest_command:
  echobell_notify:
    url: !secret echobell_webhook
    method: POST
    content_type: "application/json"
    payload: '{"title": "{{ title }}", "message": "{{ message }}"}'
```

### 민감한 정보 제한하기

알림에 어떤 데이터를 포함할지 신중하게 결정하세요:

```yaml
# Good - General information
message: "Motion detected in living room"

# Avoid - Sensitive details
message: "Security code: 1234, camera feed: http://..."
```

## 자주 발생하는 문제 해결

### 알림이 도착하지 않는 경우

1. **네트워크 연결 확인**: Home Assistant 인스턴스가 인터넷에 연결되어 있는지 확인하세요
2. **Webhook URL 확인**: 토큰까지 포함해 정확히 복사해 붙여 넣었는지 확인하세요
3. **Echobell 앱 확인**: 해당 채널을 구독하고 있는지 확인하세요
4. **Home Assistant 로그 검토**: HTTP 오류나 타임아웃이 있는지 살펴보세요

### 템플릿 오류

템플릿이 제대로 렌더링되지 않는다면:

1. 개발자 도구 → 템플릿에서 템플릿을 테스트합니다
2. Home Assistant와 Echobell의 변수 이름이 일치하는지 확인합니다
3. 템플릿 문법에 오타가 없는지 확인합니다. `{{variable}}`처럼 써야 하며 `{{ variable}}`는 안 됩니다

### 자동화가 실행되지 않는 경우

1. Home Assistant에서 트리거 조건을 확인합니다
2. 개발자 도구에서 자동화를 수동으로 실행해 봅니다
3. 엔티티 상태가 트리거 구성과 일치하는지 확인합니다
4. 디버깅을 위해 자동화 추적 기록을 검토합니다

## 예시: 전체 보안 시스템 구성

다음은 여러 보안 센서를 통합한 종합 예시입니다:

```yaml
# configuration.yaml
rest_command:
  echobell_security:
    url: !secret echobell_security_webhook
    method: POST
    content_type: "application/json"
    payload: >
      {
        "event_type": "{{ event_type }}",
        "location": "{{ location }}",
        "sensor": "{{ sensor }}",
        "timestamp": "{{ timestamp }}",
        "alarm_state": "{{ alarm_state }}"
      }

# automations.yaml
- alias: "Security Event Handler"
  trigger:
    - platform: state
      entity_id:
        - binary_sensor.front_door
        - binary_sensor.back_door
        - binary_sensor.garage_door
        - binary_sensor.motion_hallway
        - binary_sensor.motion_living_room
      to: "on"
  action:
    - service: rest_command.echobell_security
      data:
        event_type: "{{ 'door' if 'door' in trigger.entity_id else 'motion' }}"
        location: "{{ trigger.to_state.attributes.friendly_name }}"
        sensor: "{{ trigger.entity_id }}"
        timestamp: "{{ now().strftime('%Y-%m-%d %H:%M:%S') }}"
        alarm_state: "{{ states('alarm_control_panel.home_alarm') }}"
```

Echobell에서 템플릿을 다음과 같이 설정하세요:

- **제목**: `Security Alert: {{event_type | upper}}`
- **본문**: `{{location}} activated at {{timestamp}} (Alarm: {{alarm_state}})`

## 다음 단계

이제 Echobell을 Home Assistant와 연동했으니 다음을 살펴보세요:

- 다양한 알림 우선순위를 위한 [알림 유형](/docs/notification)을 살펴보세요
- 알림을 똑똑하게 필터링하는 [조건](/docs/conditions)에 대해 알아보세요
- 고급 메시지 서식을 위한 [템플릿 변수](/docs/template)를 확인해 보세요
- 최적의 연동을 위한 [Webhook 모범 사례](/docs/webhook)를 읽어 보세요

## 관련 자료

- [Home Assistant REST Command 문서](https://www.home-assistant.io/integrations/rest_command/)
- [Home Assistant RESTful Notify 플랫폼](https://www.home-assistant.io/integrations/notify.rest/)
- [Echobell Webhook 문서](/docs/webhook)
- [Echobell 템플릿 시스템](/docs/template)