# Receiving SyncTide alerts on Telegram

Your administrator wants to send you SyncTide alarm notifications through
**Telegram**. This is a free messaging app — no per-message cost, no SIM
required.

You only need to do this **once**. Total time: about 2 minutes.

---

## What you need to do

You'll do three small things:

1. Install Telegram on your phone (skip if already installed).
2. Find your **chat ID** — a number that identifies your Telegram account.
3. Open the SyncTide bot and tap **Start**, so the bot is allowed to
   message you.

Then send your chat ID to the administrator.

---

## Step 1 — install Telegram

1. Open the **App Store** (iPhone) or **Google Play** (Android).
2. Search for **Telegram**.
3. Install. Open. Sign up with your phone number.

If you already have Telegram, skip to Step 2.

---

## Step 2 — find your chat ID

1. In Telegram, tap the search icon (🔍).
2. Type **`@userinfobot`** in the search box.
3. Tap the result called **`@userinfobot`** — it has a blue checkmark next to the name.
4. Tap the **Start** button at the bottom of the screen.
5. The bot replies in a few seconds with something like:

   ```
   Id: 987654321
   First: <your name>
   Username: @<your handle>
   ```

6. The number after **`Id:`** (e.g. `987654321`) is your chat ID.
7. Copy it down or screenshot it — you'll send this to your administrator.

That's all `@userinfobot` does. You can leave or block it after this; it's a
public utility.

---

## Step 3 — open the SyncTide bot

The administrator will give you the **username** of your organisation's
SyncTide bot. It will end in `bot`, e.g. `acme_alerts_bot`.

1. In Telegram, tap the search icon (🔍).
2. Type the bot's username (with or without the `@`).
3. Tap the bot in the search results.
4. Tap **Start** at the bottom of the screen — or send the message `/start`.

You may see a short welcome message. Even if you don't, **the Start tap is
the important part** — it tells Telegram you accept messages from the bot.

> **Why this step matters.** Telegram blocks bots from messaging users who
> haven't opened the door first — it's an anti-spam protection. Without
> Step 3, alarm messages will never reach you and the system will record a
> "Forbidden: bot can't initiate conversation" error.

---

## Step 4 — send your chat ID to the administrator

Email, message, or hand over to the administrator:

- Your **chat ID** from Step 2 (e.g. `987654321`).
- Confirmation that you tapped **Start** on the SyncTide bot in Step 3.

The administrator will register you in SyncTide and start the alerts.

---

## What happens after

You'll receive alarm messages from the SyncTide bot in Telegram, just like
any other chat. They look like:

```
🔔 ALARM RAISED
Device: Pump-A
Tag: Flow
Value: 142.5 m³/h (threshold: > 120)
Time: 2026-04-30 14:23:01
```

If the administrator turned on **acknowledgements**, the message will
end with a short instruction asking you to reply.

### How to acknowledge

From v1.0.1 onwards you have three equally valid ways to close an alarm
on Telegram — pick whichever feels easiest:

1. **Swipe-reply** on the original alarm message and send any short reply
   (Telegram's reply gesture is the most precise: it matches the exact
   message even if other alarms came in afterwards).
2. **Send a simple keyword** in the same chat — any of:
   `ack`, `ok`, `okay`, `sim`, `confirmo`, `confirmar`, `yes`,
   `✅`, `👍`, `✓`. The most recent un-acknowledged alarm for you
   within the last 24 hours is closed.
3. **Reply with `ACK-xxxxxx`** if the message happens to carry a token
   (legacy format; still works).

The bot replies *"✅ Acknowledged. Escalation cancelled."* the moment
the ack lands, so you know you've closed the loop. No more typing the
weird `ACK-pW1Wp_da-jU` tokens.

When the alarm condition clears, you'll receive a follow-up:

```
✅ ALARM CLEARED
Device: Pump-A
Tag: Flow
Cleared: 2026-04-30 14:31:47
```

---

## Frequently asked

**Will the bot read my other Telegram chats?**
No. Telegram bots only see messages directed at them — your DMs, group
chats, and contacts are completely private.

**Can I mute the bot at night without missing real alarms?**
Yes — use Telegram's per-chat notification settings on the bot's chat
(swipe left → Mute). The administrator can also configure quiet hours on
SyncTide's side.

**I changed phones and lost my Telegram. Do I need to start over?**
No. Telegram accounts are tied to your phone number, not the device. Sign
in to Telegram on the new phone with the same number — your chat ID stays
the same, the bot stays opted-in, and alarms keep arriving.

**I keep getting alerts but my colleague doesn't.**
Your colleague probably skipped Step 3 (didn't tap Start on the bot). Ask
them to repeat that step — it's the most common cause.

**The bot stopped sending me messages.**
Check that you didn't accidentally block the bot. Telegram → search for
the bot → if there's an "Unblock" button, tap it. If not, ask the
administrator to look at SyncTide's messaging history for the actual
error.

---

## Reference

- Telegram website:  https://telegram.org
- iPhone:  https://apps.apple.com/app/telegram-messenger/id686449807
- Android:  https://play.google.com/store/apps/details?id=org.telegram.messenger
- Companion guide for administrators:  TELEGRAM_SETUP.md