> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/ecosystem/nodes/cpp/mytonctrl/alerting",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Telegram alerting

**MyTonCtrl Private Alerting Bot** is a tool for receiving notifications about node status via Telegram Bot.

The bot is designed to send notification messages to Telegram only. It **does not** manage the validator or process any commands.

This bot is part of the MyTonCtrl toolset and is compatible with both validators and liteservers. Create a separate private bot in Telegram and configure it within MyTonCtrl.

You can use one bot to monitor multiple nodes.

## Setup

To set up the MyTonCtrl Alerting Bot, follow these steps:

### Prepare a bot

1. Visit [@BotFather](https://t.me/BotFather) and create a bot by using the command `/newbot`. After creating a bot, copy the bot token under the "Use this token to access the HTTP API:" line.

2. Go to the bot and press the `Start` button. This action will allow the bot to send messages.

3. The bot can send messages to either private messages or groups. To receive messages from the bot in a group chat, make sure to add the bot to that group.

4. Visit [`@getmyid_bot`](https://t.me/getmyid_bot) and press the **Start** button. The bot will reply with a chat ID; use this ID to receive messages from the bot.

To receive messages in a group, add [`@getmyid_bot`](https://t.me/getmyid_bot) to the group, and it will provide the chat ID of this group.

### Activate the alert bot in MyTonCtrl

1. Enable the `alert-bot` using the following command:

   ```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
   MyTonCtrl> enable_mode alert-bot
   ```

2. Execute the command:

   ```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
   MyTonCtrl> setup_alert_bot <bot_token> <chat_id>
   ```

In case of a successful setup, the bot sends a welcome message listing all available alerts.

## Operational notes

* Alerts cover wallet balance thresholds, database usage, validator efficiency/blocks, synchronization, ADNL health, stake acceptance, slashes, and other key metrics.
* Each alert has an associated cooldown (`timeout`) to prevent spam. Info-level ok alerts reset state without sound notifications.
* The bot requires network access to the Telegram API. Ensure outbound HTTPS is permitted from the server.
* When validator mode is enabled, the alert bot automatically includes wallet and ADNL context in messages. In collator-only or other modes, some alerts may be skipped because prerequisites are missing.

## setup\_alert\_bot

**Purpose:** Configure the alert bot with the Telegram bot token and chat ID, then start sending events.

**Syntax**

```mytonctrl theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
setup_alert_bot <bot_token> <chat_id>
```

**Behavior**

* Takes the Telegram bot token and chat ID as positional parameters. Run it right after enabling `alert-bot` mode.
* Immediately attempts to send the welcome message that lists every alert. Success proves the bot has permission to write to the chat.
* On success, saves `BotToken` and `ChatId` in the local database (`myLocal.db`) so the scheduler can emit alerts. On failure, logs the Telegram error (and hints if the bot is missing from the chat).

## list\_alerts

**Purpose:** Show all predefined alerts and whether they are currently enabled.

**Syntax**

```mytonctrl theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
list_alerts
```

**Behavior**

* Lists every alert key (for example: `low_wallet_balance`, `db_usage_80`, `out_of_sync`) along with the enabled flag and the UNIX timestamp when it was last sent.
* Helps you audit which alerts are muted and whether recent warnings have fired.

## enable\_alert

**Purpose:** Re-enable a previously muted alert.

**Syntax**

```mytonctrl theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
enable_alert <alert_name>
```

**Behavior**

* Accepts any alert key defined in the alert module (for example: `low_efficiency`, `service_down`, `validator_slashed`).
* Sets the alert’s `enabled` flag to `true` so future events can trigger notifications.

**Example**

```mytonctrl theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
enable_alert low_wallet_balance
```

## disable\_alert

**Purpose:** Temporarily suppress a specific alert.

**Syntax**

```mytonctrl theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
disable_alert <alert_name>
```

**Behavior**

* Marks the alert as disabled; the scheduler skips sending messages for it until re-enabled.
* Use when you expect noisy conditions (e.g., during planned maintenance) but still want other alerts to deliver.

**Example**

```mytonctrl theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
disable_alert service_down
```

## test\_alert

**Purpose:** Send a simple message through the configured alert channel to verify connectivity.

**Syntax**

```mytonctrl theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
test_alert
```

**Behavior**

* Requires successful initialization (bot token and chat ID saved). If initialization hasn’t run yet, the command triggers it.
* Sends `Test alert` with `info` severity so you can confirm the chat receives notifications.

### Available alerts

* `low_wallet_balance`: Validator wallet balance below 10 TON while the node is working and in sync.
* `low_wallet_balance_ok`: Balance recovered to ≥10 TON after a low-balance alert.
* `db_usage_80`: TON database usage exceeded 80% (but ≤95%).
* `db_usage_95`: TON database usage exceeded 95%.
* `db_usage_ok`: Database usage dropped back below 80% after a high-usage alert.
* `low_efficiency`: Validator efficiency fell below 90% once ≥80% of the round elapsed.
* `out_of_sync`: Node stayed more than 20 seconds behind the masterchain while otherwise running.
* `sync_ok`: Node resynced to less than 20 seconds lag after an out-of-sync alert.
* `service_down`: Validator service stopped reporting as working (outside of initial sync).
* `service_down_ok`: Validator service resumed normal operation after downtime.
* `adnl_connection_failed`: Remote ADNL connectivity checks failed for all probe hosts.
* `adnl_connection_ok`: ADNL check succeeded again after a failure.
* `zero_block_created`: No blocks produced in roughly the last half validation period (\~8h on mainnet).
* `zero_block_created_ok`: Block production resumed after a zero-block alert.
* `validator_slashed`: Validator was slashed in the previous validation round.
* `stake_not_accepted`: Election stake submission was rejected (validator missing from the current validator list).
* `stake_accepted`: Election stake was accepted (validator present in the current validator list).
* `stake_returned`: Elector returned the stake during the post-freeze payout window.
* `stake_not_returned`: Stake was not returned during the expected post-freeze payout window.
* `voting`: Governance offers with ≥50% approval remain unvoted by this validator.
* `voting_ok`: All actionable governance offers have been voted on (no outstanding votes).
* `initial_sync_completed`: Initial blockchain sync finished successfully.
* `shard_collators_offline`: All registered collators for at least one shard are offline.
* `shard_collators_ok`: Collators for previously offline shards reported back online.