Telegram Notifications

Iris can push proactive messages to your phone via Telegram. When a heartbeat check-in, calendar reminder, or scheduled follow-up fires, you'll get a Telegram notification within seconds — no need to have the web UI open.

TIP

Telegram is a one-way notification channel. You read the message on your phone and tap through to the web UI for full interaction. Two-way Telegram messaging is a separate feature on the roadmap.

How It Works

When the heartbeat system generates a proactive message, two things happen in parallel:

1. The message broadcasts to the web UI via WebSocket (existing behavior)
2. The SendTelegramNotification listener sends the same message to your linked Telegram chat

Each notification includes the full message content and a "View in Iris" button that deep-links to the thread in the web UI. The button is an inline keyboard element — it doesn't count against Telegram's 4096-character message limit.

Telegram delivery is completely isolated from the web UI. If the Telegram API is down or your chat ID is wrong, the web UI message still arrives normally.

Setup

1. Create a Telegram Bot

Create a bot through BotFather on Telegram:

1. Open a chat with @BotFather
2. Send /newbot and follow the prompts to name your bot
3. Copy the bot token (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
4. Note the bot username (e.g., MyIrisBot)

2. Configure Environment

Add these variables to your .env:

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=your-bot-token-from-botfather
TELEGRAM_BOT_USERNAME=YourBotUsername

3. Register the Bot

Telegraph stores bot credentials in the database and needs a webhook so your bot can handle the /start command during account linking. Register both with:

php artisan telegraph:new-bot

The command prompts you for your bot token and name, then offers to set up the webhook automatically. When it asks to add a chat, you can skip that — Iris handles chat creation during account linking.

TIP

If you need to re-register the webhook later (e.g., after changing your domain), run php artisan telegraph:set-webhook.

4. Connect Your Account

1. Open Iris and go to Settings > Telegram Notifications
2. Click Connect Telegram
3. A link appears — click Open in Telegram (or copy the link to your phone)
4. In Telegram, tap Start when the bot chat opens
5. The settings page updates automatically once linking succeeds
6. Toggle Enable Notifications on

The linking flow uses a time-limited token (expires in 10 minutes) so only authenticated Iris users can connect their Telegram account.

TIP

Click Send Test Message after connecting to verify everything works end-to-end.

Message Format

Notifications arrive as Telegram messages with your proactive message content in Markdown, plus an inline keyboard button:

Hey — just a heads up, your meeting with Sarah starts
in 15 minutes. You mentioned wanting to bring up the
timeline for the design review.

[View in Iris]  ← tappable button linking to the thread

Long Messages

Telegram limits messages to 4096 characters. When a proactive message exceeds this, Iris truncates at the nearest sentence boundary and appends a continuation indicator:

{message content truncated at sentence boundary}... _(continued in Iris)_

[View in Iris]

The truncation is smart — it tries sentence boundaries first (. , ! , ? ), then paragraph breaks, then word boundaries as a last resort.

Configuration

Telegram settings live in config/connectors.php:

Setting	Environment Variable	Description
telegram.enabled	TELEGRAM_ENABLED	Enable Telegram integration
telegram.token	TELEGRAM_BOT_TOKEN	Bot token from BotFather
telegram.bot_username	TELEGRAM_BOT_USERNAME	Bot username for generating links

User Settings

Each user controls their own notifications in Settings > Telegram Notifications:

Setting	Description
Connect / Disconnect	Links or unlinks a Telegram chat
Enable Notifications	Toggle delivery on or off (only available when connected)
Send Test Message	Sends a test notification to verify the connection

Disconnecting clears the chat link and disables notifications. Toggling notifications off preserves the link so you can re-enable without reconnecting.

Relationship to Boundaries

Telegram notifications inherit the heartbeat boundary system for free. When a boundary is active (Quiet Hours, Do Not Disturb, Temporary Silence), the heartbeat system doesn't generate proactive messages at all — so there's nothing to notify about.

If you want proactive messages in the web UI but not on your phone, toggle Enable Notifications off in Telegram settings. The boundary system and notification toggle serve different purposes:

• Boundaries control whether Iris reaches out at all
• Notification toggle controls whether the message also goes to Telegram

Disabling Telegram Notifications

You can disable at two levels:

• Per-user: Toggle off Enable Notifications in Settings > Telegram Notifications
• System-wide: Set TELEGRAM_ENABLED=false in your .env — the settings page will show "not available" and no notifications fire for any user