Skip to main content

Telegram Integration

WASP's primary interface is a Telegram bot. The agent-telegram service bridges Telegram messages to the WASP agent core via Redis Streams.

Architecture​

Telegram API (polling)
      │
      ▼
agent-telegram (bridge)
      │ Redis Stream: events:incoming
      ▼
agent-core (EventHandler)
      │ Redis Stream: events:outgoing
      ▼
agent-telegram (bridge)
      │
      ▼
Telegram API (send message)

Setup​

1. Create a Bot​

  1. Open Telegram and message @BotFather
  2. Send /newbot
  3. Choose a name and username (must end in bot)
  4. Copy the token: 123456789:ABCdefGHIjklMNOpqrSTUVwxyz

2. Get Your User ID​

  1. Message @userinfobot on Telegram
  2. It replies with your numeric user ID (e.g., 987654321)

3. Configure Environment​

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHI...
TELEGRAM_ALLOWED_USERS=987654321  # comma-separated for multiple users

4. Set Notification Chat ID​

For scheduler alerts:

SCHEDULER_NOTIFY_CHAT_ID=987654321

Features​

Text Messages​

Send any natural language message. WASP responds with text, and may execute skills as part of the response.

Images and Screenshots​

Send images directly — WASP uses vision capabilities to analyze them. Screenshots taken by the browser skill are sent back automatically.

Video​

Send video files — WASP extracts the first frame and uses vision to analyze it.

Documents​

Send documents (PDF, code files, etc.) — WASP can read and analyze them.

Commands​

CommandDescription
/startInitialize conversation
/model <name>Switch active AI model
/api set <provider> <key>Set API key at runtime
/api listList configured providers
/introspectGet agent health and capability report
/memory <query>Search memories directly

Live Progress Updates​

During multi-skill execution, WASP edits a status message in real-time:

⚙️ Ejecutando: web_search...
⚙️ Ejecutando: fetch_url → python_exec...
⚙️ Ejecutando: write_file...

When the final response arrives, the progress message is deleted and replaced with the full response.

Important: If the progress message edit fails (e.g., message too old), it is silently dropped — a new progress message is never sent as fallback. This prevents message flooding.

Allowed Users Security​

TELEGRAM_ALLOWED_USERS is a comma-separated list of numeric Telegram user IDs. All other users are silently ignored.

To allow multiple users:

TELEGRAM_ALLOWED_USERS=987654321,123456789,456789012

Polling Mode​

WASP uses polling mode (not webhooks). This means:

  • No domain or SSL required for Telegram specifically
  • No port 443 needed for the Telegram bridge
  • Works behind NAT without configuration

The bridge calls getUpdates every few seconds. Response time is typically 1-3 seconds from message send to first response.

Message Size Limits​

  • Telegram messages: 4,096 characters max
  • Long responses are automatically split into multiple messages
  • Code blocks preserved intact
  • Images sent as separate messages

Troubleshooting​

Bot not responding:

# Check telegram bridge logs
docker compose logs agent-telegram --tail=50

# Verify token is correct
curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"

# Check your user ID is in allowed list
echo $TELEGRAM_ALLOWED_USERS

Slow responses:

  • Check docker compose logs agent-core --tail=20
  • Large skill chains (browser, code execution) can take 30-60 seconds
  • The progress indicator shows the agent is working

"Not allowed" (no response):

  • Your Telegram user ID is not in TELEGRAM_ALLOWED_USERS
  • Add your ID and restart: docker compose restart agent-telegram