> For the complete documentation index, see [llms.txt](https://xgine.gitbook.io/xgine-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xgine.gitbook.io/xgine-docs/advanced-features/push-notifications.md).

# Push Notifications

Never miss important events! Receive real-time alerts on your phone or desktop even when you're away from your computer.

***

## 📱 Supported Platforms

| Platform       | Features                          |
| -------------- | --------------------------------- |
| **Discord**    | Webhook messages with screenshots |
| **Telegram**   | Bot messages with screenshots     |
| **Pushbullet** | Push notes with screenshots       |

***

## 💬 Discord Setup

<details>

<summary><strong>Step 1: Create a Webhook</strong></summary>

1. Open your Discord server
2. Go to **Server Settings** → **Integrations** → **Webhooks**
3. Click **New Webhook**
4. Name it (e.g., "Ragnabot Alerts")
5. Copy the webhook URL

</details>

<details>

<summary><strong>Step 2: Configure in Ragnabot</strong></summary>

1. Open Ragnabot settings
2. Navigate to Push Notifications
3. Paste the webhook URL in the **Discord Webhook URL** field
4. Save settings

</details>

{% hint style="success" %}
**Pro Tip:** Create a dedicated channel for bot alerts to keep them organized!
{% endhint %}

***

## 📲 Telegram Setup

<details>

<summary><strong>Step 1: Create a Bot</strong></summary>

1. Open Telegram and message [@BotFather](https://t.me/BotFather)
2. Send `/newbot`
3. Follow the instructions to name your bot
4. Copy the **bot token** provided

</details>

<details>

<summary><strong>Step 2: Get Your Chat ID (Automatic)</strong></summary>

1. Enter your **Bot Token** in Ragnabot
2. Send a message to your bot on Telegram (or add it to a group)
3. Click the **⟳ refresh button** next to the Chat ID field
4. Ragnabot will automatically fetch available chats
5. If multiple chats are found, select from the list

{% hint style="info" %}
**Note:** The bot must receive at least one message before it can detect chats.
{% endhint %}

</details>

<details>

<summary><strong>Alternative: Manual Chat ID</strong></summary>

1. Message your new bot (send any message)
2. Visit: `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
3. Find your **chat ID** in the response
4. Enter it manually in the Chat ID field

</details>

***

## 📤 Pushbullet Setup

<details>

<summary><strong>Step 1: Get API Key</strong></summary>

1. Go to [Pushbullet Settings](https://www.pushbullet.com/#settings)
2. Click **Create Access Token**
3. Copy the token

</details>

<details>

<summary><strong>Step 2: Configure in Ragnabot</strong></summary>

1. Paste the token in the **Pushbullet API Key** field
2. Save settings

</details>

***

## 🚨 Alert Types

Each alert type can be toggled ON/OFF using the switches in the Push Notification panel.

### Critical Alerts

| Alert         | Toggle       | Trigger               | Urgency |
| ------------- | ------------ | --------------------- | :-----: |
| **❤️ Low HP** | Configurable | HP drops below 10%    | 🔴 High |
| **💀 Death**  | Configurable | Character dies        | 🔴 High |
| **🌀 Warp**   | Configurable | Unexpected map change | 🔴 High |

{% hint style="info" %}
**New:** Low HP alerts now have an independent toggle switch, allowing you to control HP notifications separately from other alert types.
{% endhint %}

### Warning Alerts

| Alert             | Toggle           | Trigger                       |  Urgency  |
| ----------------- | ---------------- | ----------------------------- | :-------: |
| **📦 Overweight** | `bts_overweight` | Inventory exceeds limit       | 🟡 Medium |
| **🚫 Stuck**      | `bts_stucked`    | No movement for extended time | 🟡 Medium |

### Status Updates

| Alert                | Toggle       | Trigger                    | Urgency |
| -------------------- | ------------ | -------------------------- | :-----: |
| **📊 Status Update** | `bts_update` | Periodic interval (30 min) |  🟢 Low |

{% hint style="warning" %}
**Important:** If ALL toggles are OFF, no notifications will be sent to any service, even if API keys are configured.
{% endhint %}

***

## ⏱️ Cooldown Settings

Prevent notification spam with smart cooldowns:

| Event         | Default Cooldown |
| ------------- | :--------------: |
| HP Alert      |     5 minutes    |
| Death Alert   |     5 minutes    |
| Warp Alert    |     5 minutes    |
| Overweight    |    10 minutes    |
| Stuck Alert   |    10 minutes    |
| Status Update |    30 minutes    |

***

## 📸 Screenshot Attachments

All notifications can include screenshots of your game:

| Platform       | Screenshot Format |
| -------------- | ----------------- |
| **Discord**    | Embedded image    |
| **Telegram**   | Photo message     |
| **Pushbullet** | File attachment   |

{% hint style="info" %}
Screenshots help you quickly assess the situation without needing to check your computer.
{% endhint %}

***

## 🧪 Testing Your Setup

Use the **Test** button to verify your configuration:

1. Fill in the credentials for the services you want to use
2. Click the **Test** button
3. A notification will show the results:
   * ✅ **Success**: "All X notification(s) sent successfully!"
   * ⚠️ **Partial**: "X OK, Y failed. Check console for details."
   * ❌ **Failed**: "All X notification(s) failed."

{% hint style="info" %}
The Test button bypasses toggle switches and always sends a test notification.
{% endhint %}

***

## 💡 Best Practices

<details>

<summary><strong>Optimizing Your Notifications</strong></summary>

1. **Enable Critical Alerts** — Always have Death and Warp alerts on
2. **Use Multiple Services** — Configure both Discord and Telegram for redundancy
3. **Adjust Cooldowns** — Default cooldowns prevent spam (3-30 minutes)
4. **Test First** — Always send a test notification to verify setup
5. **Check Toggle Switches** — Make sure at least one toggle is ON

</details>

<details>

<summary><strong>Troubleshooting</strong></summary>

| Issue                             | Solution                                                 |
| --------------------------------- | -------------------------------------------------------- |
| No notifications received         | Check if at least one toggle switch is ON                |
| Telegram not working              | Ensure you've messaged the bot first, then click refresh |
| Discord webhook error             | Verify the webhook URL is correct and the channel exists |
| Pushbullet `invalid_access_token` | Get a new Access Token from Pushbullet settings          |

</details>


---

# 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://xgine.gitbook.io/xgine-docs/advanced-features/push-notifications.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.