haos-blueprints/Common/Telegram Commands/blueprint.yaml

# Telegram Commands Blueprint
# Responds to Telegram bot commands by executing callback actions.
# See README.md for detailed documentation.

blueprint:
  name: "Custom: Telegram Commands"
  description: >
    Responds to Telegram bot commands (like /start, /help) by executing
    corresponding callback actions. Supports up to 8 commands with
    individual callbacks and optional reply messages.
  domain: automation

  input:
    # -------------------------------------------------------------------------
    # Access Control
    # -------------------------------------------------------------------------
    access_group:
      name: "Access Control"
      collapsed: true
      input:
        allowed_chat_ids:
          name: Allowed Chat IDs
          description: >
            List of Telegram chat IDs allowed to trigger this automation.
            Leave empty to allow all chat IDs (no filtering).
            Can be user IDs (positive) or group IDs (negative).
          default: []
          selector:
            text:
              multiple: true

    # -------------------------------------------------------------------------
    # Command Configuration
    # -------------------------------------------------------------------------
    commands_group:
      name: "Commands"
      collapsed: false
      input:
        commands:
          name: Command List
          description: >
            List of Telegram commands to respond to (include the "/" prefix).
            Example: ["/status", "/lights_on", "/arm_alarm"]
          default: []
          selector:
            text:
              multiple: true

        answers:
          name: Reply Messages (optional)
          description: >
            Reply message for each command (same order as commands list).
            Leave empty to not send any reply for that command.
          default: []
          selector:
            text:
              multiple: true

    # -------------------------------------------------------------------------
    # Command Callbacks
    # -------------------------------------------------------------------------
    callbacks_group:
      name: "Callbacks"
      collapsed: false
      input:
        command_1_callback:
          name: Command 1 Callback
          description: Actions to run when first command is received
          default: []
          selector:
            action: {}

        command_2_callback:
          name: Command 2 Callback
          description: Actions to run when second command is received
          default: []
          selector:
            action: {}

        command_3_callback:
          name: Command 3 Callback
          description: Actions to run when third command is received
          default: []
          selector:
            action: {}

        command_4_callback:
          name: Command 4 Callback
          description: Actions to run when fourth command is received
          default: []
          selector:
            action: {}

        command_5_callback:
          name: Command 5 Callback
          description: Actions to run when fifth command is received
          default: []
          selector:
            action: {}

        command_6_callback:
          name: Command 6 Callback
          description: Actions to run when sixth command is received
          default: []
          selector:
            action: {}

        command_7_callback:
          name: Command 7 Callback
          description: Actions to run when seventh command is received
          default: []
          selector:
            action: {}

        command_8_callback:
          name: Command 8 Callback
          description: Actions to run when eighth command is received
          default: []
          selector:
            action: {}

# Parallel mode allows multiple commands to be processed simultaneously
mode: parallel

# =============================================================================
# Trigger
# =============================================================================
trigger:
  # Listen for Telegram command events
  - platform: event
    event_type: telegram_command
    id: "telegram_command"

# =============================================================================
# Variables
# =============================================================================
variables:
  # Input references
  commands: !input commands
  answers: !input answers
  allowed_chat_ids: !input allowed_chat_ids

  # Callback references (needed for condition checks)
  command_1_callback: !input command_1_callback
  command_2_callback: !input command_2_callback
  command_3_callback: !input command_3_callback
  command_4_callback: !input command_4_callback
  command_5_callback: !input command_5_callback
  command_6_callback: !input command_6_callback
  command_7_callback: !input command_7_callback
  command_8_callback: !input command_8_callback

  # Extract command and chat ID from trigger event
  received_command: "{{ trigger.event.data.command | default('') }}"
  chat_id: "{{ trigger.event.data.chat_id | default('') }}"
  user_id: "{{ trigger.event.data.user_id | default('') }}"

  # Check if chat ID is allowed (empty list = allow all)
  is_chat_allowed: >
    {{ allowed_chat_ids | length == 0 or (chat_id | string) in allowed_chat_ids }}

  # Find the index of the received command in our list
  # Returns -1 if command not found or callback is empty
  command_index: >
    {% set ns = namespace(idx=-1) %}
    {% for i in range(commands | length) %}
      {% if received_command == commands[i] %}
        {% set ns.idx = i %}
      {% endif %}
    {% endfor %}
    {{ ns.idx }}

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

# =============================================================================
# Condition - Only proceed if we received a valid command from allowed chat
# =============================================================================
condition:
  - condition: template
    value_template: "{{ received_command != '' and command_index >= 0 and is_chat_allowed }}"

# =============================================================================
# Actions
# =============================================================================
action:
  # ---------------------------------------------------------------------------
  # Debug Logging (optional)
  # ---------------------------------------------------------------------------
  - choose:
      - conditions:
          - condition: template
            value_template: "{{ is_debug }}"
        sequence:
          - service: persistent_notification.create
            data:
              title: "Telegram Commands Debug"
              message: >
                Received command: {{ received_command }}
                Chat ID: {{ chat_id }}
                User ID: {{ user_id }}
                Chat allowed: {{ is_chat_allowed }}

                Command index: {{ command_index }}
                Commands list: {{ commands }}
                Answers list: {{ answers }}
                Allowed chat IDs: {{ allowed_chat_ids if allowed_chat_ids | length > 0 else '(all)' }}

  # ---------------------------------------------------------------------------
  # Execute Command Callback
  # ---------------------------------------------------------------------------
  - choose:
      - conditions: "{{ command_index == 0 and command_1_callback | length > 0 }}"
        sequence: !input command_1_callback
      - conditions: "{{ command_index == 1 and command_2_callback | length > 0 }}"
        sequence: !input command_2_callback
      - conditions: "{{ command_index == 2 and command_3_callback | length > 0 }}"
        sequence: !input command_3_callback
      - conditions: "{{ command_index == 3 and command_4_callback | length > 0 }}"
        sequence: !input command_4_callback
      - conditions: "{{ command_index == 4 and command_5_callback | length > 0 }}"
        sequence: !input command_5_callback
      - conditions: "{{ command_index == 5 and command_6_callback | length > 0 }}"
        sequence: !input command_6_callback
      - conditions: "{{ command_index == 6 and command_7_callback | length > 0 }}"
        sequence: !input command_7_callback
      - conditions: "{{ command_index == 7 and command_8_callback | length > 0 }}"
        sequence: !input command_8_callback

  # ---------------------------------------------------------------------------
  # Send Reply Message (if configured)
  # ---------------------------------------------------------------------------
  - variables:
      reply_message: >
        {% if command_index >= 0 and command_index < (answers | length) %}
          {{ answers[command_index] }}
        {% else %}
        {% endif %}

  - choose:
      - conditions: "{{ reply_message | trim | length > 0 }}"
        sequence:
          - service: telegram_bot.send_message
            data:
              target: "{{ chat_id }}"
              message: "{{ reply_message }}"