Chapter 04

Alerts (Telegram)

The panel can send a Telegram message to your staff the moment a door is forced (opened without a fob, exit button or remote unlock) or held open longer than the time you set on the door. The message arrives on the phones of whoever is in the chat within a couple of seconds of the door reporting it, so a propped fire door or a forced back door is noticed while somebody can still do something about it.

Each tenant (each gym, site or customer) has its own bot and its own destination chat, so one site never sees another site's alerts. Every alert is always written to the Log (chapter 11) whether or not Telegram is set up; Telegram is a second copy that reaches people who are not looking at the panel.

What is alerted

Both need a door position sensor (reed switch or door contact) wired to the controller; without one the controller cannot tell that the door is open, and neither alert is ever raised. Chapter 5 covers the wiring.

Nothing else is sent to Telegram in the current release: denied scans, offline controllers, failed firmware updates and system events stay in the Log only.

You need two things, both from Telegram itself:

1. A bot token: a long string that identifies your bot.
2. A chat ID: the number of the chat, group or channel the bot should post into.

Both are pasted into Settings > Alerts (Telegram) in the panel. The whole job takes about five minutes and needs no technical knowledge; follow the parts below in order.

Part A: create the bot with @BotFather

1. Open Telegram (phone or desktop) and, in the search box at the top, type BotFather. Pick the one with the blue verified tick and the name BotFather. Press Start if you see a Start button.
2. Type /newbot and send it.
3. BotFather asks for a name. This is the display name people will see, for example Anytown Gym Doors. Send it.
4. BotFather asks for a username. It must end in bot and contain no spaces, for example anytowngym_doors_bot. If it says the username is taken, try another one. Send it.
5. BotFather replies with a message that starts "Done! Congratulations on your new bot" and contains a line like:

Use this token to access the HTTP API:
123456789:AAH4kZ9yq2f_ExampleExampleExample

The part after "HTTP API:" (numbers, a colon, then letters) is the bot token. Tap it once in Telegram to copy it.

Warning: keep the token private. Anyone with the token can send messages as your bot. Do not paste it into group chats or tickets; if it leaks, send /revoke to BotFather for that bot and paste the new token into the panel.

You can get the token again at any time by sending /mybots to BotFather, choosing your bot, then API Token.

Part B: get the chat ID

Telegram does not show chat IDs anywhere in its normal screens, which is why this step trips people up. There are three ways, easiest first.

Way 1 (recommended): the panel's Find my chat ID button

1. Decide where alerts should go:
   • A private chat with one person: that person opens Telegram, searches for the bot's username (for example @anytowngym_doors_bot), opens it and presses Start, then sends any message, for example hello.
   • A group (several staff): create the group (or use an existing one), add the bot as a member (Group info > Add member > search for the bot's username), then send any message in the group, for example hello.
   • A channel (announcement style, nobody replies): open the channel's info > Administrators > Add administrator > search for the bot's username and add it. Then post one message in the channel.
2. In the panel go to Settings, open the Alerts (Telegram) section, paste the bot token into Bot token and click Find my chat ID.
3. A table headed Chats this bot can see appears listing every chat the bot has noticed, with its name, type (private, group, supergroup or channel) and ID, most recent first. Click Use this next to the right one. The chat ID is saved and the panel confirms with "Chat ID ... saved - tick Enable, then Send test message".
4. If the panel says the bot has not seen any chats yet: send another message to the bot, or in the group or channel, wait a few seconds, and click Find my chat ID again. If it is a group, also read "Privacy mode" below.

Way 2: read it from the bot's update feed in a browser

1. Send a message to the bot (or in the group or channel it is in) as above.
2. In a web browser open this address, replacing TOKEN with your bot token (keep the word bot directly in front of the token, no space):

https://api.telegram.org/botTOKEN/getUpdates

For example https://api.telegram.org/bot123456789:AAH4kZ9yq2f_Example/getUpdates.

1. You will see a block of text. Look for "chat":{"id": and the number right after it is the chat ID, for example:

"chat":{"id":987654321,"first_name":"Sam","type":"private"}

or, for a group:

"chat":{"id":-1001234567890,"title":"Front desk","type":"supergroup"}

1. Copy that number (including the minus sign if there is one) into Chat ID in the panel.

If the page shows {"ok":true,"result":[]} the bot has not received anything yet: send a message and refresh the page.

Way 3: rules of thumb for groups and channels

• Private chat: a positive number, for example 987654321.
• Group: add the bot to the group and send a message. Group IDs are negative. Normal groups look like -123456789; larger groups ("supergroups") look like -1001234567890. Telegram may upgrade a group to a supergroup when you change certain settings, which changes its ID: if alerts stop after you reorganised a group, run Find my chat ID again.
• Channel: the bot must be added as an administrator (a plain member of a channel cannot post). Post one message in the channel. The ID always starts with -100.

Privacy mode: why a bot in a group may see nothing

By default a bot added to a group only sees messages that are commands (starting with /) or that mention it. That means Find my chat ID and getUpdates may show nothing even though you have been chatting in the group. Two fixes; either works:

• Make the bot a group administrator (Group info > Administrators > Add administrator). Admin bots see every message.
• Turn privacy mode off: send /mybots to BotFather, pick the bot, choose Bot Settings > Group Privacy > Turn off. If the bot is already in the group you must remove it and add it again for the change to take effect.

Alternatively just type a command in the group, for example /start, which the bot always sees.

For sending alerts none of this matters: the bot can always post into a group it is a member of. Privacy mode only affects what it can read, which is only needed to discover the chat ID.

Part C: put it in the panel and test

Open Settings and expand the Alerts (Telegram) section (it shows a green on badge once alerts are enabled). Viewers cannot see Settings; admins and custom roles with the Settings permission can (chapter 12). A super admin sets it up per tenant after switching in.

All three buttons save what is typed first, so nothing you entered is lost when you click one of the helpers.

Step by step:

1. Paste the bot token into Bot token.
2. Put the chat ID in Chat ID, or use Find my chat ID and click Use this on the right row.
3. Tick Enable Telegram alerts, and check that Door forced and Door held open are ticked as you want them (both are on by default).
4. Click Send test message. Within a couple of seconds the message "Test from Access Controller (your site name)" should appear in the chat. The panel shows a green "Test message sent - check Telegram", or a red "Test message NOT sent:" followed by the reason (see the troubleshooting table below).
5. Click Save alert settings.

Then open Doors, click each door that has a door sensor, and set Alert if held open for N seconds to suit that door (chapter 3). The default is 60; 0 switches the held-open alert off for that door. The value is sent to the door's controller automatically within seconds.

Tip: test the real thing once, not just the test button. Open a sensor-equipped door with the exit button and hold it past its held-open time; the Door held open message should arrive and the Log should show the same alert. Then open it from outside without a fob (with the relay pulse long finished) to see Door forced.

Cooldown and what is logged

• Repeated alerts of the same type for the same door are limited to one Telegram message per minute, so a bouncing sensor or a door that is opened and closed repeatedly cannot flood the chat. The Log still records every alert; only the Telegram copy is suppressed, and the panel's server log notes "suppressed (cooldown)" when that happens.
• The message is sent in the background, so a slow or unreachable Telegram never delays the controller or the Log.
• If a send fails (wrong chat, bot removed from the group, no internet from the panel) the failure is written to the panel's server log as "telegram send failed"; nothing is shown in the web interface, which is why the Send test message button exists. Re-test after any change to the bot, the group or the chat.
• The bot token is stored in the tenant's settings in the panel database and is never rendered back into a page. Chapter 15 lists it with the other secrets.

The panel host needs outbound HTTPS to api.telegram.org (chapter 16). Controllers do not talk to Telegram; only the panel does.

Troubleshooting

The exact message shown in red after Send test message or Find my chat ID is the best thing to pass on to whoever supports your panel. The common ones: