Telegram Bot

Connect HELIX to Telegram for mobile notifications and basic agent commands. The Telegram integration lets you stay informed about task activity and interact with your agents on the go.

Setting Up the Bot

Step 1: Create a Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot
3. Follow the prompts to name your bot (e.g., "HELIX Mission Control")
4. BotFather gives you a bot token — copy it

Step 2: Connect to HELIX

Add the bot token to your HELIX configuration:

Via the onboarding wizard: Paste the token in the Telegram step during first setup.

Via environment variables:

# In your .env file
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxyz
TELEGRAM_ALLOWED_USER_IDS=12345678,87654321

Via Settings: Go to Settings > Integrations > Telegram and paste the bot token.

Step 3: Get Your User ID

To receive notifications, HELIX needs your Telegram user ID:

1. Message @userinfobot on Telegram
2. It replies with your user ID (a number like 12345678)
3. Add this to TELEGRAM_ALLOWED_USER_IDS or enter it in your user profile settings

Step 4: Enable Notifications

Each user controls their own Telegram notifications:

1. Go to Settings > Profile in the HELIX dashboard
2. Toggle Telegram Notifications on
3. Enter your Telegram User ID
4. Save

Notification Types

The Telegram bot sends the same notifications as the in-app bell:

Notification	Example Message
Task Assigned	"Task 'Write blog post' assigned to Sierra"
Task Completed	"Sierra completed 'Write blog post'"
Approval Needed	"Task 'Write blog post' needs your review"
Agent Error	"Sierra encountered an error on 'Write blog post'"
Mention	"Clement mentioned you in a comment on 'Write blog post'"

Security

Allowed User IDs

The TELEGRAM_ALLOWED_USER_IDS environment variable restricts which Telegram users can interact with the bot. Only listed user IDs can:

• Receive notifications
• Send commands to the bot

This prevents unauthorized users from accessing your HELIX instance through Telegram.

Bot Token Security

Keep your bot token secret. If compromised:

1. Go to @BotFather and use /revoke
2. Create a new token
3. Update the token in HELIX settings
4. Restart HELIX services

Troubleshooting

Bot Not Sending Notifications

1. Verify the bot token is correct in .env or Settings
2. Check that your Telegram user ID is in TELEGRAM_ALLOWED_USER_IDS
3. Confirm Telegram notifications are enabled in your HELIX profile
4. Make sure you've messaged the bot at least once (Telegram requires this before a bot can message you)
5. Check backend logs: docker compose logs backend | grep telegram

Bot Not Responding to Commands

1. Verify the bot is running: check gateway logs for Telegram connection
2. Confirm your user ID is in the allowed list
3. Restart the gateway: docker compose restart gateway