haos-blueprints/Common/Periodic Notification/blueprint.yaml

# Periodic Notification
# Sends notifications at specified times on a repeating day schedule.
# See README.md for detailed documentation.
#
# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

blueprint:
  name: "Custom: Periodic Notification"
  description: >
    Sends notifications at specified times every N days when a control
    flag is enabled. Supports multiple notification targets and flexible
    scheduling.
  domain: automation

  input:
    # -------------------------------------------------------------------------
    # Notification Configuration
    # -------------------------------------------------------------------------
    notification:
      name: "Notification"
      collapsed: false
      input:
        notify_targets:
          name: Notification Targets
          description: >
            Notify entities to send notifications to
            (e.g., notify.mobile_app_phone).
          selector:
            entity:
              domain: notify
              multiple: true

        message:
          name: Message
          description: The notification message to send.
          selector:
            text:
              multiline: true

    # -------------------------------------------------------------------------
    # Schedule Configuration
    # -------------------------------------------------------------------------
    schedule:
      name: "Schedule"
      collapsed: false
      input:
        notification_times:
          name: Notification Times
          description: >
            Comma-separated list of times in 24-hour format with leading
            zeros (e.g., "08:00, 14:30, 20:00").
          selector:
            text:

        day_interval:
          name: Day Interval
          description: >
            How often to send notifications (in days).
            Set to 1 for daily notifications.
          default: 1
          selector:
            number:
              min: 1
              max: 365
              mode: box
              unit_of_measurement: days

        start_date:
          name: Start Date (optional)
          description: >
            Reference start date for the day interval calculation.
            Notifications are sent every N days counting from this date.
            Leave empty to ignore the day interval and send every day.
          default: ""
          selector:
            date:

    # -------------------------------------------------------------------------
    # Control
    # -------------------------------------------------------------------------
    control:
      name: "Control"
      collapsed: false
      input:
        control_flag:
          name: Control Flag (optional)
          description: >
            Toggle entity to enable or disable notifications.
            Notifications are only sent when this entity is ON.
            Leave empty to always send notifications.
          default: ""
          selector:
            entity:
              domain:
                - input_boolean
                - switch

# Single mode prevents overlapping notification sends
mode: single

# =============================================================================
# Trigger Variables (available in trigger templates)
# =============================================================================
trigger_variables:
  input_times: !input notification_times

# =============================================================================
# Triggers
# =============================================================================
trigger:
  # Fire when the current time matches any configured notification time
  - platform: template
    value_template: >
      {{ now().strftime('%H:%M') in (input_times.split(',') | map('trim') | list) }}

# =============================================================================
# Variables
# =============================================================================
variables:
  # Input references
  notify_targets: !input notify_targets
  message_text: !input message
  interval: !input day_interval
  start_date: !input start_date
  control_flag: !input control_flag

  # Debug flag - set to true to enable persistent notifications for troubleshooting
  is_debug: false

# =============================================================================
# Conditions
# =============================================================================
condition:
  # Control flag must be ON (skipped if no control flag)
  - condition: template
    value_template: >
      {%- if control_flag | length == 0 -%}
        true
      {%- else -%}
        {{ is_state(control_flag, 'on') }}
      {%- endif -%}

  # Today must fall on the correct day in the interval cycle (skipped if no start date)
  - condition: template
    value_template: >
      {%- if start_date | length == 0 -%}
        true
      {%- else -%}
        {%- set today_ts = as_timestamp(now().strftime('%Y-%m-%d') ~ 'T00:00:00') -%}
        {%- set start_ts = as_timestamp(start_date ~ 'T00:00:00') -%}
        {%- set days_since = ((today_ts - start_ts) / 86400) | round(0) | int -%}
        {{ days_since >= 0 and days_since % (interval | int) == 0 }}
      {%- endif -%}

# =============================================================================
# Actions
# =============================================================================
action:
  # ---------------------------------------------------------------------------
  # Debug Logging (optional)
  # ---------------------------------------------------------------------------
  - choose:
      - conditions:
          - condition: template
            value_template: "{{ is_debug }}"
        sequence:
          - service: persistent_notification.create
            data:
              title: "Periodic Notification Debug"
              message: >
                Targets: {{ notify_targets }}
                Message: {{ message_text }}
                Interval: every {{ interval }} day(s)
                Start Date: {{ start_date }}

  # ---------------------------------------------------------------------------
  # Send Notification
  # ---------------------------------------------------------------------------
  - service: notify.send_message
    target:
      entity_id: "{{ notify_targets }}"
    data:
      message: "{{ message_text }}"