# Telegram Bot Connector

## What It Does
Your Gipity agent is available on Telegram via @GipityAI_bot. Users message the bot and get the same AI capabilities as the web interface - chat, images, audio, code execution, web search, and more - directly in Telegram DMs.

## How Users Connect

**New users (no Gipity account):**
1. Open Telegram and search for **@GipityAI_bot**
2. Tap **Start** (or send `/start`)
3. Accept the Terms of Service when prompted
4. Start chatting - a Gipity account is created automatically

**Existing users (link your account):**
1. Use `/connect telegram` in the Gipity web interface, OR ask the agent "connect my Telegram"
2. Click the personalized link - it opens the bot in Telegram
3. Your existing Gipity account is linked automatically (same agent, memory, projects)

**Disconnect:**
- Use `/disconnect telegram` in the web interface, OR ask the agent "disconnect Telegram"

No signup form, no email, no password. The bot handles everything.

## Auto-Provisioning
When a Telegram user first accepts ToS:
- A Gipity account is created with a synthetic email (`telegram-{id}@connector.gipity.ai`)
- A default agent, home project, and initial free credits are granted
- A "Telegram" conversation is created and reused for all future messages
- The user can later log into the web interface to access advanced features

## What Works in Telegram
- **Text messages** - full chat with streaming responses (progressive message editing)
- **Image generation** - images sent as Telegram photos
- **Audio generation** - clips sent as Telegram audio files (speech, music, sound effects)
- **Code execution** - sandbox runs, results returned as text
- **Web search and Twitter search** - results formatted as text
- **Photo analysis** - send a photo to the bot and it's analyzed by the LLM
- **App deployment** - deploy URL sent with an "Open App" inline button
- **Tweet cards** - formatted as readable text blocks

## Limitations
- **DMs only** - group chats are not supported yet
- **No file uploads** - only photos can be sent to the bot (no documents, audio, etc.)
- **No destructive confirmations** - operations like DROP TABLE or recursive delete are auto-skipped (users are directed to the web interface)
- **Message length** - Telegram caps messages at 4096 characters; long responses are automatically split
- **No interactive flows** - no multi-step confirmations or approval dialogs

## For Users Asking About Telegram
If a user asks "how do I use Gipity on Telegram?" or "can I connect to Telegram?", tell them:
1. Search for @GipityAI_bot on Telegram
2. Tap Start and accept the Terms of Service
3. Start chatting - everything is automatic

If they already use the web interface and want to link their Telegram account, you can use the `connector_manage` tool with action "connect" and provider "telegram" to generate a one-time linking URL. Alternatively, they can use `/connect telegram` in the web interface.

If they want to disconnect Telegram, use the `connector_manage` tool with action "disconnect" and provider "telegram". They can also use `/disconnect telegram` in the web interface.

## Technical Details (For Reference)
- Streaming: progressive message editing throttled to ~1 edit/second
- Rich content: images as photos, audio as audio files, deploy URLs as inline keyboard buttons
- Database: `connector_users` table maps Telegram user IDs to Gipity accounts