Telegram Notification Bot
=========================

A simple companion Telegram bot that monitors your ATM's LNbits wallet and sends
you a notification when:

- someone makes a withdrawal from the ATM, or
- the wallet balance drops below a configured threshold.

It lives in the ``telegram_notification_bot/`` directory of the repository. It is
a standalone Python script (no third-party dependencies) and is **not** part of
the ESP32 firmware build.

Prerequisites
-------------

- A server or computer that stays online 24/7 (e.g. a Raspberry Pi, a VPS, or a
  home server).
- A Telegram account.

Setup
-----

1. Create a Telegram bot
~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Open Telegram and search for **@BotFather**.
2. Send ``/newbot`` and follow the prompts to choose a name and username.
3. BotFather replies with a **bot token** (looks like
   ``123456789:ABCdefGhIJKlmNoPQRsTUVwxYZ``) — save it.

2. Get your Telegram chat ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Search for **@userinfobot** (or any "chat ID" bot) on Telegram.
2. Send it any message — it replies with your **chat ID** (a number like
   ``123456789``).

3. Get your LNbits API key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Log in to your LNbits instance.
2. Open the wallet connected to your ATM.
3. Copy the **read-only API key** (not the admin key).

4. Configure the bot
~~~~~~~~~~~~~~~~~~~~~~

Open ``main.py`` and fill in the configuration variables at the top of the file:

.. code-block:: python

   url = "https://legend.lnbits.com/api/v1/wallet"  # your LNbits instance URL
   api_key = "ABCDEFG"                                # your LNbits read-only API key
   bot_token = "123:ABC"                              # your Telegram bot token from BotFather
   chat_id = "123456789"                              # your Telegram chat ID

   min_balance = 1000       # notify when balance drops below this many sats
   refresh_interval = 5600  # how often to check the balance, in seconds

5. Run the bot
~~~~~~~~~~~~~~~

.. code-block:: bash

   python3 main.py

The bot runs in an infinite loop, checking the wallet balance every
``refresh_interval`` seconds.

To keep it running after you close your terminal, use ``screen``, ``tmux``, or a
systemd service:

.. code-block:: bash

   # Quick option: run in the background with screen
   screen -S atmbot
   python3 main.py
   # Press Ctrl+A, then D to detach. Reattach later with: screen -r atmbot