Telegram alerts and chat

An alert on your phone with every order, and the ability to ask the shop questions from the same place.

It is optional: unconfigured, it does not exist.

Setting it up

1 · Create the bot. Message @BotFather, /newbot, and keep the token it gives you.

2 · Get your chat_id. Send anything to your bot and open https://api.telegram.org/bot<TOKEN>/getUpdates. It is in message.chat.id.

3 · Put it in .env:

TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_IDS=111111,222222
TELEGRAM_WEBHOOK_SECRET=<something long and random>
TELEGRAM_WEBHOOK_URL=https://your-shop/telegram/webhook

With Docker (docker-compose.full.yml) the backend reads the whole .env, so these variables reach it like any other: put them there and restart the container.

4 · Register the webhook:

npm run pcc -- ejecutar ./src/scripts/telegram-alta.ts

It sends you a test message if it worked.

The alerts

The bot writes to every chat on the list when:

Each alert goes out once per order, even if the event is retried.

The language of the alerts

Alerts are sent by events, outside any request, so there is no "language of whoever is asking". It is chosen once, in the .env:

TELEGRAM_IDIOMA=es     # or en

Without it, or with a language there is no text for, they go out in English. The same setting applies to the bot's fixed replies ("I didn't know what to answer", "I couldn't look it up: …"), to the test message of step 4 and to the copilot's answers when you ask it something over Telegram.

Talking to the shop

Write to the bot in plain language and it answers with real data: sales, stock, orders, customers. It is the same copilot as the panel.

Over Telegram it only reads; it changes nothing. In the panel a proposed change is reviewed with its values in front of you and approved with the mouse; on a phone it gets confirmed with a thumb, walking down the street, unread.

Who can use it

Telegram does not let you make a private bot. That is not a limitation of this system: bots are public by design and there is no setting in BotFather to hide or restrict them. Careful with /setprivacy, whose name misleads — it only decides whether the bot sees every message inside a group.

So the control lives here: only the chat_ids on the list are answered. Anyone else gets nothing back, not even "you are not allowed", because that alone confirms the bot exists and that there is a shop behind it. They are left looking at a silent chat.

Without that list, a stranger who finds the bot could ask it about your orders and walk away with your customers' names, addresses and phone numbers.

Adding someone later

With the webhook active, getUpdates stops working — messages go to one place or the other, never both. So to add a second person:

1. Have them message the bot. It will not reply: they are not authorised yet.
2. Their chat_id lands in the server log: telegram: mensaje de un chat NO autorizado — chat_id=… (@usuario)
3. Add it to TELEGRAM_CHAT_IDS and restart.

The webhook secret

The route is public: anyone who guesses the URL can call it. Telegram sends TELEGRAM_WEBHOOK_SECRET back in a header, and anything without it is dropped.

With no secret configured, the route rejects everything. That is deliberate: an open route that runs AI over your shop's data cannot be left alive by an oversight in .env.

A name that does not give you away

@myshop_bot is findable by anyone searching for your brand. A name unrelated to the shop stops people stumbling onto it — but that adds to the allowlist, it does not replace it. The list is what actually protects you.

If something fails

An alert that does not go out does not stop the order: it is noted in the log and that is that. Selling is what matters; being told about it is the convenience.

To check the webhook's health: https://api.telegram.org/bot<TOKEN>/getWebhookInfo — it carries the last error, if there was one.