Skip to main content
HAPI integrates with Telegram to provide mobile notifications and a full-featured Mini App for session control.

​
Overview

Mini App

Full HAPI interface inside Telegram

Notifications

Permission requests and session updates

Deep Links

Jump directly to specific sessions

Inline Actions

Approve/deny permissions with buttons

​
Setup

​
1. Create a Telegram Bot

1

Open BotFather

Message @BotFather on Telegram
2

Create Bot

Send /newbot and follow the prompts
3

Get Token

Copy the bot token (format: 123456:ABC-DEF...)

​
2. Configure the Hub

Set these environment variables: 
export TELEGRAM_BOT_TOKEN="your-bot-token-from-botfather"
export HAPI_PUBLIC_URL="https://your-domain.example"
Telegram Mini Apps require HTTPS. You cannot use http:// or localhost. Use a tunnel service like Cloudflare Tunnel if your hub isn’t publicly accessible.

​
3. Start the Hub

hapi hub
The bot will start automatically and register commands with Telegram.

​
4. Bind Your Telegram Account

1

Open Bot

Find your bot on Telegram and send /start
2

Open Mini App

Tap “Open App” button
3

Login

Enter your CLI API token: CLI_API_TOKEN:namespace
4

Done

Your Telegram account is now bound
The namespace suffix (:namespace) is optional. Omit it for the default namespace.

​
Configuration Options

​
Required

VariableDescriptionExample
TELEGRAM_BOT_TOKENToken from @BotFather123456:ABC-DEF...
HAPI_PUBLIC_URLPublic HTTPS URLhttps://hapi.example.com

​
Optional

VariableDefaultDescription
TELEGRAM_NOTIFICATIONtrueEnable/disable notifications
CLI_API_TOKENAuto-generatedShared secret for authentication

​
Mini App Features

The Telegram Mini App provides the full HAPI experience:

Session List

View all active and past sessions

Chat Interface

Send messages and view responses

Permission Control

Approve or deny tool access

File Browser

Browse files and view git diffs

Terminal Access

Remote terminal via web interface

Session Creation

Spawn new sessions on any machine

​
Accessing the Mini App

Open the Mini App in several ways:
  1. Bot Command: Send /app to your bot
  2. Start Command: Send /start and tap “Open App”
  3. Deep Link: Tap notification links
  4. Telegram Menu: Use the Mini App menu button

​
Notifications

HAPI sends notifications for important events:

​
Permission Requests

When an AI agent needs your approval: 
🔔 Permission Request

Session: my-project
Agent: Claude Code

Requests permission to edit files:
- src/index.ts
- src/utils.ts

[Approve] [Deny] [View Session]
Tap Approve or Deny directly in the notification, or View Session to see full context in the Mini App.

​
Session Ready

When a session completes a task: 
✅ Session Ready

Session: my-project
Agent: Claude Code

Task completed. Ready for your input.

[Open Session]

​
Notification Settings

To disable notifications: 
export TELEGRAM_NOTIFICATION=false
hapi hub
Or mute notifications in Telegram:
  • Right-click bot → Mute
HAPI generates deep links that jump directly to specific sessions: 
https://t.me/your_bot?start=session_abc123
Deep links are included in:
  • Permission request notifications
  • Session ready notifications
  • Manually generated session links
  1. User taps notification link
  2. Telegram opens your bot
  3. Bot launches Mini App with session ID
  4. Mini App navigates to that session

​
Bot Commands

The HAPI bot supports these commands:
CommandDescription
/startWelcome message with Mini App link
/appOpen the Mini App directly
All interactive features (viewing sessions, sending messages, etc.) are in the Mini App, not bot commands.

​
Architecture

How Telegram integration works: 
┌─────────────┐
│   Telegram  │
│   User      │
└──────┬──────┘
       │
       │ (Mini App WebView)
       ▼
┌─────────────┐         ┌─────────────┐
│  Mini App   │◄───────►│  HAPI Hub   │
│  (React)    │   API   │  (Server)   │
└─────────────┘         └──────┬──────┘
                               │
                               ▼
                        ┌─────────────┐
                        │ Telegram    │
                        │ Bot API     │
                        └─────────────┘
                               │
                               ▼
                        (Notifications)

​
Authentication Flow

  1. User opens Mini App in Telegram
  2. Mini App sends Telegram initData to hub
  3. Hub verifies initData with Telegram
  4. Hub checks if Telegram ID is bound to namespace
  5. Hub issues JWT token
  6. Mini App uses JWT for API requests

​
Use Cases

​
Mobile-First Workflow

Use Telegram as your primary mobile interface:
  1. Start session on desktop: hapi
  2. Get notification on Telegram when permission needed
  3. Approve directly in notification
  4. Get notified when task completes
  5. Open Mini App to send next instruction

​
Notification-Only Mode

Use Telegram just for notifications:
  1. Enable Telegram integration
  2. Use PWA for main interface
  3. Get critical alerts via Telegram
  4. Act on notifications when convenient

​
Multi-User Teams

Each team member can bind their Telegram:
  1. Each user gets their own namespace
  2. Each user binds Telegram with CLI_API_TOKEN:username
  3. Notifications go to the right person
  4. No shared Telegram account needed

​
Advantages Over PWA

Better iOS Support

No Safari limitations, full push notifications

No Installation

Works immediately, no install step

Telegram Ecosystem

Integrates with existing Telegram workflow

Reliable Notifications

Uses Telegram’s robust notification system

​
Security Considerations

​
Bot Token

Keep your bot token secure:
  • Never commit to git
  • Use environment variables
  • Rotate if compromised

​
Binding

Telegram binding is secure:
  • Uses Telegram’s initData verification
  • Cryptographically signed by Telegram
  • Can’t be spoofed

​
Public URL

Your HAPI_PUBLIC_URL should:
  • Use HTTPS (required by Telegram)
  • Be accessible only to authorized users
  • Use authentication (CLI_API_TOKEN)
Don’t expose your hub publicly without authentication. Always require CLI_API_TOKEN for access.

​
Troubleshooting

  • Verify TELEGRAM_BOT_TOKEN is correct
  • Check hub logs for errors
  • Ensure hub is running
  • Test token with Telegram’s API
  • Verify HAPI_PUBLIC_URL uses HTTPS (not HTTP)
  • Check CORS settings include Telegram domains
  • Ensure hub is accessible from public internet
  • Test URL in browser first
  • Check TELEGRAM_NOTIFICATION=true
  • Verify Telegram account is bound
  • Ensure bot isn’t muted in Telegram
  • Check hub logs for send errors
  • Verify CLI_API_TOKEN is correct
  • Check namespace if using multi-user setup
  • Ensure hub is running and accessible
  • Try logging in via web first

​
Tunneling for Development

Telegram requires HTTPS. For local development: 
cloudflared tunnel --url http://localhost:3006
Use the generated https:// URL as HAPI_PUBLIC_URL.

​
ngrok

ngrok http 3006
Use the forwarding URL as HAPI_PUBLIC_URL.

​
Tailscale

Enable HTTPS on your Tailscale network and use your machine’s Tailscale URL.
For production deployments, use a proper domain with SSL certificate instead of tunnels.

PWA

Alternative mobile experience

Remote Control

Switch between local and remote

Permissions

Control agent access to tools

Build docs developers (and LLMs) love

Get started for freeTalk to us