> For the complete documentation index, see [llms.txt](https://dozza.gitbook.io/pulsechain_node_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dozza.gitbook.io/pulsechain_node_guide/part-9-monitoring-with-telegram.md).

# Part 9 — Monitoring with Telegram (optional)

A lightweight watchdog that messages you on Telegram if the node stops advancing or the RPC stops responding. It runs as a small cron job on the node, needs no extra software beyond `curl`, and only alerts on a **state change** (healthy → stuck/down, and recovery) so it never spams you. A healthy node stays silent.

## 9.1 Create a Telegram bot

1. In Telegram, open `@BotFather` (the official one) and send `/newbot`.
2. Give it a display name, then a unique username ending in `bot`.
3. BotFather replies with a **bot token** (e.g. `123456789:AAF-xxxxxxxxxxxxxxxxxxxxx`). Keep it private — anyone with it can send as your bot.

## 9.2 Get your chat ID

1. Search for your new bot, open the chat, and send it any message (e.g. `/start`). The bot won't reply — that's normal, it has no code yet — but this lets it message you later.
2. In a browser, visit (keep `bot` directly in front of the token):

```
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
```

3. In the JSON, find `"chat":{"id":123456789` — that number is your **chat ID**. If the result is empty, send the bot another message and refresh.

{% hint style="info" %}
**Verify the token quickly.** Visiting `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getMe` should return your bot's name. An error there means the token was copied wrong.
{% endhint %}

## 9.3 Create the watchdog script

Create `/blockchain/node_watch.sh` with the following contents, filling in your bot token and chat ID:

```bash
#!/bin/bash
# node_watch.sh — Telegram alert if the node's block stops advancing.
# Alerts only on a STATE CHANGE (ok -> stuck/down, and recovery).

RPC="http://127.0.0.1:8545"
STATE_FILE="/blockchain/.node_watch_state"
BOT_TOKEN="<YOUR_BOT_TOKEN>"
CHAT_ID="<YOUR_CHAT_ID>"

send_alert() {
    curl -s --max-time 10 \
        "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
        -d chat_id="${CHAT_ID}" \
        -d parse_mode="HTML" \
        -d text="$1" > /dev/null 2>&1
}

resp=$(curl -s --max-time 10 -X POST "$RPC" \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}')
hex=$(echo "$resp" | grep -o '"result":"0x[0-9a-fA-F]*"' | grep -o '0x[0-9a-fA-F]*')

prev_block=0; prev_status="ok"
if [ -f "$STATE_FILE" ]; then
    read -r prev_block prev_status < "$STATE_FILE"
    [ -z "$prev_block" ] && prev_block=0
    [ -z "$prev_status" ] && prev_status="ok"
fi
now=$(date '+%Y-%m-%d %H:%M:%S %Z')

if [ -z "$hex" ]; then
    if [ "$prev_status" != "down" ]; then
        send_alert "NODE DOWN - RPC not responding at ${now}."
    fi
    echo "$prev_block down" > "$STATE_FILE"; exit 0
fi

cur_block=$((hex))
if [ "$cur_block" -gt "$prev_block" ]; then
    if [ "$prev_status" != "ok" ]; then
        send_alert "NODE RECOVERED - block advancing again (now ${cur_block})."
    fi
    echo "$cur_block ok" > "$STATE_FILE"
else
    if [ "$prev_status" != "stuck" ]; then
        send_alert "NODE STUCK - block stopped at ${cur_block} at ${now}."
    fi
    echo "$cur_block stuck" > "$STATE_FILE"
fi
```

Make it executable:

```bash
chmod +x /blockchain/node_watch.sh
```

## 9.4 Test it end to end

```bash
/blockchain/node_watch.sh        # first run: records baseline, no alert

docker stop execution            # simulate a failure
/blockchain/node_watch.sh        # should send a NODE DOWN message

docker start execution           # recover; wait ~20s for it to advance
/blockchain/node_watch.sh
/blockchain/node_watch.sh        # once advancing: sends NODE RECOVERED
```

## 9.5 Schedule it with cron

```bash
crontab -e        # if prompted for an editor the first time, choose nano (1)

# add this line at the bottom, then save and exit:
*/3 * * * * /blockchain/node_watch.sh
```

It now checks every 3 minutes, silently, alerting only on a change of state. PulseChain blocks are \~10s, so a healthy node advances well within each interval — no false alarms.

{% hint style="warning" %}
**Blind spot: total host failure.** This runs **on** the node, so a full power cut or VM death stops the watchdog too — it can't alert you if the whole machine is gone. It reliably catches the common cases (container crashed, node stuck, sync stalled, RPC hung). For true "is the box alive" coverage, add an **external** check from another device or a free uptime service.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://dozza.gitbook.io/pulsechain_node_guide/part-9-monitoring-with-telegram.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.