@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/telegram.md

@@ -0,0 +1,379 @@
+# Skill Deep-Dive: telegram
+
+**Skill**: `telegram` (via clawdbot)
+**Category**: Agent Reachability
+**Setup Difficulty**: 🟢 Easy
+**Time Estimate**: ~5-10 minutes
+**Platform**: Cross-platform
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| Agent texting | Users can DM your agent on Telegram | Send "What's on my calendar?" |
+| Group chat | Agent can participate in Telegram groups | Add bot to team channel |
+| Media sharing | Send/receive images, videos, voice | Send screenshot for analysis |
+| Voice messages | Agent can send voice audio | `[[audio_as_voice]]` flag |
+| Pairing system | Secure user approval flow | Only approved users can chat |
+| Webhook + polling | Flexible deployment options | Local dev vs production |
+
+---
+
+## Why Telegram is EASIEST for Agent Reachability
+
+| Channel | Phone Required? | Verification? | API Access | Setup Time |
+|---------|-----------------|---------------|------------|------------|
+| **Telegram** | ❌ No | ❌ None | ✅ Free, easy | ~5 min |
+| WhatsApp | ✅ Real SIM | ⚠️ QR code | ✅ Works | ~10 min |
+| iMessage | ✅ Apple ID | ⚠️ Apple blocks | ❌ Requires Mac | 30+ min |
+| Email | ❌ No | ✅ OAuth | ✅ Works | ~20 min |
+| SMS | ✅ Twilio | ✅ Paid | ✅ Works | ~15 min |
+
+**Telegram wins because**: No phone number needed for the bot, no verification headaches, free API, works everywhere.
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] Telegram account — For creating the bot via @BotFather
+- [ ] `TELEGRAM_BOT_TOKEN` — From @BotFather
+- [ ] Node.js runtime — For running clawdbot
+
+### Soft Dependencies (Recommended)
+- [ ] `1password` skill — For storing bot token securely
+- [ ] Domain + SSL — For webhook mode (production)
+- [ ] `tmux` — For running bot in background
+
+### This Skill Enables
+- [ ] Text-based agent interaction — Users can chat with agent anywhere
+- [ ] Proactive notifications — Agent can message users (reminders, alerts)
+- [ ] Morning briefings — Scheduled messages to your phone
+- [ ] Cross-platform access — Telegram works on phone, desktop, web
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check for Node.js
+which node && node --version || echo "❌ Need Node.js"
+
+# Check for clawdbot
+ls ~/nexus/home/projects/clawdbot 2>/dev/null && echo "✅ clawdbot exists"
+```
+
+### Step 1: Create Telegram Bot
+
+1. Open Telegram and message [@BotFather](https://t.me/BotFather)
+2. Send `/newbot`
+3. Choose a name (e.g., "Echo Assistant")
+4. Choose a username (must end in `bot`, e.g., `echo_nexus_bot`)
+5. Copy the bot token (looks like `123456789:ABCdefGHIjklMNO...`)
+
+### Step 2: Store Token Securely
+
+```bash
+# Store in 1Password (recommended)
+op item create --category login \
+  --title "Telegram Bot - Echo" \
+  --vault Personal \
+  credential="YOUR_BOT_TOKEN_HERE"
+
+# Or export to environment
+export TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN_HERE"
+```
+
+### Step 3: Configure clawdbot
+
+```bash
+cd ~/nexus/home/projects/clawdbot
+
+# Create/edit config
+cat >> clawdbot.yml << 'EOF'
+telegram:
+  token: ${TELEGRAM_BOT_TOKEN}
+  dmPolicy: pairing  # Secure: requires approval
+  # Or: dmPolicy: open  # Anyone can message
+  # Or: allowFrom: ["your_telegram_id"]
+EOF
+```
+
+### Step 4: Run the Bot
+
+```bash
+# Development mode (polling)
+cd ~/nexus/home/projects/clawdbot
+bun run telegram
+
+# Production mode (webhook)
+bun run telegram:webhook
+```
+
+### Verification
+
+```bash
+# Test the bot
+# 1. Open Telegram
+# 2. Search for your bot username
+# 3. Send it a message
+# 4. Should get pairing code response (if dmPolicy: pairing)
+```
+
+---
+
+## Configuration
+
+### DM Policies
+
+```yaml
+telegram:
+  dmPolicy: pairing   # (Default) New users get pairing code, need approval
+  # dmPolicy: open    # Anyone can DM
+  # dmPolicy: allowlist  # Only users in allowFrom
+  # dmPolicy: disabled   # No DMs allowed
+  
+  allowFrom:
+    - "123456789"       # Telegram user ID
+    - "@username"       # Telegram username
+```
+
+### Approve a Pairing Request
+
+When someone messages your bot with `dmPolicy: pairing`:
+
+```bash
+# They receive: "Pairing code: ABC123"
+# You approve with:
+clawdbot pairing approve telegram ABC123
+```
+
+### Group Chat Configuration
+
+```yaml
+telegram:
+  groupPolicy: open      # Allow all groups
+  # groupPolicy: allowlist  # Only allowed groups
+  # groupPolicy: disabled   # No groups
+  
+  requireMention: true   # Require @botusername in groups
+  
+  groups:
+    "-1001234567890":    # Group chat ID
+      enabled: true
+      requireMention: false  # Always respond in this group
+      systemPrompt: "You are a helpful team assistant"
+```
+
+---
+
+## User Actions Required
+
+1. **Create Telegram account** (if don't have one)
+2. **Message @BotFather** to create bot
+3. **Copy bot token** and store securely
+4. **Configure clawdbot.yml** with token
+5. **Run the bot** (polling or webhook)
+6. **Approve users** via pairing (if using pairing mode)
+
+---
+
+## Common Failure Points
+
+### Failure: "Bot token invalid"
+
+**Symptom**: Bot fails to start with auth error
+
+**Cause**: Token copied incorrectly or revoked
+
+**Recovery**:
+```bash
+# Verify token format (should be NUMBER:LETTERS)
+echo $TELEGRAM_BOT_TOKEN | grep -E "^[0-9]+:[A-Za-z0-9_-]+$"
+
+# If invalid, get new token from @BotFather
+# Send /revoke to revoke old, /token to see current
+```
+
+**Prevention**: Copy full token including the number prefix
+
+---
+
+### Failure: "User not authorized"
+
+**Symptom**: User messages bot but gets pairing code
+
+**Cause**: User not in allowFrom list and dmPolicy is pairing/allowlist
+
+**Recovery**:
+```bash
+# Approve via pairing code
+clawdbot pairing approve telegram <CODE>
+
+# Or add to allowFrom in config
+```
+
+**Prevention**: Document the pairing flow for users
+
+---
+
+### Failure: Webhook not receiving updates
+
+**Symptom**: Bot works in polling but not webhook mode
+
+**Cause**: HTTPS not configured, wrong URL, firewall
+
+**Recovery**:
+```bash
+# Check webhook status
+curl https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo
+
+# Delete webhook to reset
+curl https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/deleteWebhook
+
+# Set webhook again
+curl https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook?url=https://your.domain/telegram-webhook
+```
+
+**Prevention**: Use polling for local dev, webhook only for production
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Create bot via @BotFather | ❌ No | - | Interactive Telegram chat |
+| Store token | ✅ Yes | 1Password | `op item create` |
+| Configure clawdbot | ✅ Yes | bash | Write config file |
+| Start bot | ✅ Yes | bash/tmux | `bun run telegram` |
+| Approve pairing | ✅ Yes | bash | `clawdbot pairing approve` |
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| First message | User texts bot, gets intelligent response | Right after setup |
+| Voice message | Send voice, agent transcribes and responds | Show multimedia support |
+| Morning briefing | Agent proactively messages at 8am | After cron setup |
+| Group assistant | Bot helps in team Telegram group | For team use cases |
+| Image analysis | Send screenshot, agent analyzes it | Show vision capability |
+
+### Demo Script
+
+```
+User: [Messages bot on Telegram] "What's the weather today?"
+
+Agent: "Currently 72°F and sunny in Austin. Perfect day to work outside! ☀️"
+
+User: [Sends voice message] "Remind me to call mom tomorrow"
+
+Agent: "Got it! I'll remind you tomorrow to call your mom. Want me to set a specific time?"
+
+---
+
+Agent: [Next morning, 8am, proactive message]
+"Good morning! 🌅 Today's forecast: sunny, high of 75°F. 
+
+You have:
+• 10am - Team standup
+• 2pm - Dentist appointment
+• Reminder: Call mom
+
+Have a great day!"
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **cron** | Scheduled messages | Morning briefings, reminders |
+| **gog** | Calendar/email access | "What's on my calendar?" |
+| **eve** | iMessage access | Cross-channel search |
+| **comms** | Unified messages | Search all channels |
+| **weather** | Weather data | Include in briefings |
+| **computer-use** | Screenshots | Send visual updates |
+
+---
+
+## Testing Checklist
+
+- [ ] Created bot via @BotFather
+- [ ] Bot token stored securely
+- [ ] clawdbot.yml configured
+- [ ] Bot starts without errors
+- [ ] Can message bot in DM
+- [ ] Pairing flow works (if enabled)
+- [ ] Can add bot to group
+- [ ] Bot responds to @mentions in group
+- [ ] Media (images) work
+- [ ] Voice messages work
+- [ ] Webhook mode works (if production)
+
+---
+
+## Notes for Onboarding Agent
+
+- **RECOMMEND THIS FIRST** for agent reachability — Easiest by far
+- **No phone number needed** — Unlike WhatsApp/iMessage
+- **Free API** — No costs for basic usage
+- **Pairing is secure default** — Don't recommend "open" unless trusted
+- **Works everywhere** — Phone, desktop, web browser
+- **When to recommend**:
+  - User wants to text their agent
+  - User doesn't want to deal with Apple ID / WhatsApp hassles
+  - User wants group chat functionality
+- **When NOT to recommend**:
+  - User doesn't have/want Telegram
+  - User requires SMS (use Twilio instead)
+- **Time estimates**:
+  - Bot creation: 2 minutes
+  - Configuration: 3 minutes
+  - First message: 5 minutes total
+
+---
+
+## Advanced: Multi-Account Support
+
+clawdbot supports multiple Telegram accounts:
+
+```yaml
+telegram:
+  accounts:
+    personal:
+      token: ${TELEGRAM_PERSONAL_TOKEN}
+      allowFrom: ["123456789"]
+    work:
+      token: ${TELEGRAM_WORK_TOKEN}
+      allowFrom: ["*"]  # Open for work bot
+```
+
+---
+
+## Security Considerations
+
+- **Bot token is SECRET** — Store in 1Password, not in code
+- **Pairing mode** — Secure by default, requires approval
+- **Group IDs** — Anyone who knows can invite bot
+- **Webhook URL** — Must be HTTPS, verifiable
+- **User IDs** — More reliable than usernames for allowlists
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*