# Telegram order alerts in Go (GoCommerce module)

> Tell a GoCommerce store’s owner about each new order, payment, cancellation and return on Telegram, through a bot of their own: setup, wording, retries, limits.

- Canonical: https://kitcommerce.store/integrations/telegram-alerts/
- Last updated: 2026-10-28

---

Messaging

## Telegram order alerts in Go

A Go package that writes to the store’s owner, not its shoppers, on Telegram. The owner makes a bot with @BotFather, sends it a message, picks that chat under Notifications › Setup Telegram, and every new order, payment, cancellation and return arrives there as it happens. No provider account, and no price per message.

- **Messaging** module
- **5** settings
- **23** tests
- **10** API operations
- **ext/telegram-alerts**

### What it does

In the package’s words it is not a notifier: the engine’s notifiers write to shoppers, on a channel the shopper gave, and this writes to the owner about the shop. It subscribes to four events, order.created, order.paid, order.cancelled and order.returned, and words each one as a short plain-text message: the order number, the total, the items, the customer’s first name, the payment, and a link to the order in the panel when the panel’s address is set.

Each alert can be switched off or reworded on the Setup Telegram screen, with a live preview. The wording is a template over the same flat order data the engine’s own templates read, so {{.order_number}} means one thing everywhere, and only the alerts the owner changed are stored, so a default improved in a release reaches every store that never touched it. Wording that would not render is refused as it is saved.

The sending follows the webhooks module’s shape. The subscriber only writes a row and returns, so a Telegram that takes ten seconds to answer never holds the engine’s outbox, and a refusal is recorded against the alert rather than returned to the outbox, which would re-run every other consumer of the event. A worker sends, with backoff and a dead state.

### Configuration

Two settings, both normally typed on the Notifications › Setup Telegram screen: the bot token and the chat. Config can carry them for a store wired in its own main(), and the screen’s values win. The reference binary reads neither from the environment, because a bot and a chat belong to one owner.

*Telegram module settings — 5 settings, 2 required*

| Setting | Environment variable | Required | What it does |
| --- | --- | --- | --- |
| `BotToken` Bot token | — | Yes | From @BotFather in Telegram: send it /newbot and it answers with a token like 123456789:AAE…. Checked for that shape before use. It travels in the Bot API’s URL path, so no error that could quote it is logged, stored or answered as it stands. |
| `ChatID` Chat ID | — | Yes | Where the alerts go: the owner’s own chat with the bot, or a group it is in. Find my chat lists the chats that have written to the bot lately, or the ID can be typed. With a token and a chat in Config the plugin starts switched on. |
| `Timeout` | — | No | Bounds one call to Telegram: 10 seconds when zero. Go only; not in the panel. |
| `BaseURL` | — | No | Replaces https://api.telegram.org. The package says tests set it and nothing else should. Go only. |
| `Client` | — | No | Replaces the HTTP client. Go only; not in the panel. |

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own `main()` you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

### Setting it up

1. **Make a bot** — In Telegram, send /newbot to @BotFather and keep the token it answers with. Then send your new bot a message, or add it to the group the alerts should go to.
2. **Install the module** — Pass telegramalerts.New to gocommerce.New, as below, or start the reference binary with -telegram, which installs it idle.
3. **Set it up** — Under Notifications › Setup Telegram, save the token, press Find my chat and pick yours, then Send test message. The test works before the alerts are switched on.
4. **Switch the alerts on** — Turn on Send alerts. Reword or switch off any of the four alerts there, and watch Recent alerts for what arrived and what Telegram answered.

main.go

```
import (
	"github.com/itswadesh/gocommerce/core"
	telegramalerts "github.com/itswadesh/gocommerce/ext/telegram-alerts"
)

app, err := gocommerce.New(cfg, telegramalerts.New(telegramalerts.Config{}))
```

The package doc’s own example, with its imports; cfg is your gocommerce.Config. With an empty Config the module installs idle and each store sets its own bot and chat on the Setup Telegram screen, which is how the reference binary’s -telegram flag and examples/store/main.go install it. Import path `github.com/itswadesh/gocommerce/ext/telegram-alerts`.

### How it works

- **Queued, then sent**

  Each event becomes one row holding the message as it was worded when the event happened. A worker claims 20 at a time with FOR UPDATE SKIP LOCKED every five seconds, and sooner when an alert has just been queued.

- **One message per event**

  A unique key on the event id means the engine redelivering an event, which its outbox may do, never becomes a second message on the owner’s phone.

- **Retries with backoff**

  When Telegram cannot be reached, is busy or asks to slow down, the alert waits and goes again, the wait doubling up to 15 minutes and honouring Telegram’s retry_after, for 12 attempts. Then it is marked dead and kept.

- **A refusal stops at once**

  An unknown chat, a blocked bot or a revoked token is a 4xx Telegram will give again, so the alert is marked dead with the reason in words the owner can act on, and can be sent again from Recent alerts once the setting is fixed.

- **Plain text, no previews**

  Messages go as plain text, so a customer’s name with an underscore in it cannot break the formatting, with link previews off. A message is cut at 3,500 characters, under Telegram’s limit.

- **Money as a person reads it**

  The total is written with the currency’s sign and decimals, and a rupee amount is grouped in lakhs and crores: ₹1,29,900.00, not 12990000 paise.

### What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

- **Four events** — New order, payment received, order cancelled and return received. Shipping, delivery and refunds send no alert.
- **One chat per store** — Every alert goes to the one chat the store chose. There is no routing of some events to one person and others to another.
- **Nothing queued while off** — An event that happens while the alerts are switched off is not queued for later. Alerts already queued when they are switched off wait for the switch rather than being thrown away.
- **Find my chat needs no webhook** — The chat list comes from the Bot API’s getUpdates, which Telegram refuses for a bot that has a webhook set. Such a bot’s chat ID is typed by hand.
- **The order link needs the panel’s address** — The link into the panel is built from the install’s panel URL, GOCOMMERCE_PANEL_URL. Without it the alert carries no link rather than a guessed one.
- **The log holds no text** — Recent alerts shows each alert’s event, state, attempts and Telegram’s last answer, not the message, because it carries a customer’s name.

FAQ

### Questions about the Telegram module

**Does it cost anything?**

The package doc puts it this way: a bot writing to its owner costs nothing, with no account with a provider, no wording registered with a carrier and no price per message. The bot is the owner’s own, made with @BotFather.

**Can it write to a group?**

Yes. Add the bot to the group, send a message there, and pick the group with Find my chat. If the group becomes a supergroup, Telegram moves it to a new chat ID, and the alert’s reason says to choose it again.

**Who can change the alerts?**

The module adds two rights. alerts.read, which managers have by default, sees the alerts, their wording and whether they arrived. alerts.write, which only the owner has until it is granted, rewords them, finds the chat, sends a test and retries one that failed.

**Does it message shoppers?**

No. It writes only to the chat the store chose. What shoppers are sent is the engine’s notifiers’ job, under Notifications.

**Is Telegram a partner?**

No. The module calls Telegram’s public Bot API with a token you supply. Telegram does not endorse GoCommerce, and no store is known to run this module in production yet.

### Related modules

Each is a directory under `ext/`, imported the same way. Where this one fits in the store: [What modules add to a direct-to-consumer store](https://kitcommerce.store/solutions/d2c/).

- [MSG91 SMS API in Go Text shoppers about their GoCommerce orders through MSG91’s DLT-approved flow templates: the auth key, a template per event, and what the module leaves out.](https://kitcommerce.store/integrations/notify-msg91/)
- [Resend email API in Go Send GoCommerce order emails through Resend with one setting, an API key: the default sender, where the wording lives, what gets logged, and the limits.](https://kitcommerce.store/integrations/notify-resend/)
- [SendGrid email API in Go Send GoCommerce order emails through SendGrid’s v3 API: the API key and verified sender, where the wording lives, retries, and what the module leaves out.](https://kitcommerce.store/integrations/notify-sendgrid/)
- [Twilio SMS API in Go Text shoppers about GoCommerce orders through Twilio: account SID, auth token, a from number or messaging service, the engine’s wording, and the limits.](https://kitcommerce.store/integrations/notify-twilio/)

### Source

Everything on this page is read from [`ext/telegram-alerts`](https://github.com/itswadesh/gocommerce/tree/main/ext/telegram-alerts) in the GoCommerce repository, MIT licensed. When this page and the code disagree, the code is right and this page is out of date.Telegram is a trademark of its owner; this module talks to its public API and implies no endorsement. See [trademarks](https://kitcommerce.store/about/#trademarks).

- [ext/telegram-alerts on GitHub](https://github.com/itswadesh/gocommerce/tree/main/ext/telegram-alerts)
- [Telegram](https://telegram.org)
- [All GoCommerce modules](https://kitcommerce.store/integrations/)

### Try it against a store of your own

The backend + admin quick start runs GoCommerce’s API and admin on your own machine, without a storefront. Add this module to it and try it on test orders before a real one depends on it.

[Backend + admin quick start](https://kitcommerce.store/#one-command) · [Read the module](https://github.com/itswadesh/gocommerce/tree/main/ext/telegram-alerts) · [All integrations](https://kitcommerce.store/integrations/)