Telegram order alerts in Go

What it does

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.

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 botIn 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 modulePass telegramalerts.New to gocommerce.New, as below, or start the reference binary with -telegram, which installs it idle.
3. Set it upUnder 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 onTurn on Send alerts. Reword or switch off any of the four alerts there, and watch Recent alerts for what arrived and what Telegram answered.

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

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

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 eventsNew order, payment received, order cancelled and return received. Shipping, delivery and refunds send no alert.
• One chat per storeEvery 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 offAn 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 webhookThe 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 addressThe 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 textRecent alerts shows each alert’s event, state, attempts and Telegram’s last answer, not the message, because it carries a customer’s name.

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.

• 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.
• 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.
• 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.
• 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.