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

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugins/ pages for correct interfaces and manifests.
> Canonical locations: API auth = /api/authentication, webhook verification = /api/webhooks, rate limits = /resources/rate-limiting, transaction statuses = /fundamentals/payment-flow.
> The documentation uses the Diataxis framework: Tutorials (learning), How-to (tasks), Reference (lookup), Explanation (understanding).

# Telegram Notifications

> Receive real-time push notifications for payment events directly in a Telegram chat using the telegram-bot addon.

The **telegram-bot** addon sends instant push notifications to a Telegram chat whenever key payment events occur. This is faster than email and ideal for operators who want real-time alerts on their phone.

<Note>
  You need a Telegram Bot API token and a target chat ID before configuring this addon. Both are free to obtain.
</Note>

## Prerequisites

1. Open Telegram and message **@BotFather**
2. Send `/newbot` and follow the prompts to create your bot
3. Copy the **Bot API Token** BotFather gives you
4. Add your bot to a group or channel, or start a direct chat with it
5. Send a message in that chat, then visit `https://api.telegram.org/bot<TOKEN>/getUpdates` to find your **chat ID**

## Install and configure

<Steps>
  <Step>
    Install the **telegram-bot** addon. See [Addons](/docs/system/addons) for installation instructions.
  </Step>

  <Step>
    Go to **System > Addons**, find **Telegram Bot**, and click **Settings**.
  </Step>

  <Step>
    Enter your **Bot API Token** and **Chat ID** in the fields provided.
  </Step>

  <Step>
    Toggle **Active** and select which brands should send Telegram notifications.
  </Step>

  <Step>
    Click **Save**. A test message is sent to confirm the connection.
  </Step>
</Steps>

## Supported events

The Telegram bot sends notifications for these events:

* `payment.completed` - Payment received successfully
* `payment.failed` - Payment attempt failed
* `refund.issued` - Refund processed

Each notification includes the transaction amount, currency, gateway name, customer email (partial), and a link to the transaction in the admin panel.

<Warning>
  Transaction amounts and partial customer identifiers are visible in Telegram messages. Only add the bot to private chats or trusted team groups. Avoid public channels.
</Warning>

## Troubleshooting

| Symptom                          | Likely cause                            | Fix                                                                                        |
| -------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ |
| Bot does not receive updates     | Privacy mode is blocking group messages | Send `/setprivacy` to @BotFather and select **Disable** for your bot                       |
| `401 Unauthorized` error         | Invalid or revoked bot token            | Regenerate the token via @BotFather and update the addon settings                          |
| No messages delivered            | Wrong chat ID                           | Re-fetch your chat ID using `getUpdates` and verify the bot is a member of the target chat |
| Messages arrive but lack details | Addon not activated for the brand       | Go to addon settings and ensure the correct brand is toggled active                        |

## Related Pages

* [Addons](/docs/system/addons) - Install and manage addons including telegram-bot
* [Email Notifications](/docs/notifications/email) - Alternative notification channel via SMTP
* [Companion App](/docs/mobile/companion-app) - Android app for SMS-based verification and notifications


## Related topics

- [Email Notifications](/docs/notifications/email.md)
- [Addons](/docs/system/addons.md)
- [Integration Plugin Development](/docs/developer/plugin-types/integration.md)
- [Acknowledge Push Notifications](/docs/api-reference/acknowledge-push-notifications.md)
- [List Companion App Notifications](/docs/api-reference/list-companion-app-notifications.md)