Telegram

Connect Telegram for quick, mobile-friendly conversation. Your agent appears as a Telegram bot.

How it works

Message your bot on Telegram. It sends an instant ack (“Cooking…”, “On it…”, etc.), processes your message, and replies.

You message bot → platform receives webhook → instant ack sent
                → message queued → sandbox wakes → agent processes
                → reply sent → ack deleted

Setup

1. Create a Telegram bot

   Open Telegram and message @BotFather. Use /newbot to create a bot. Copy the bot token.

2. Add the token in your dashboard

   Go to your TinyFat dashboard → Settings → Integrations → Telegram Bot Token. Paste the token.

3. Set the webhook URL

   TinyFat registers the webhook automatically when you save the token.

4. Message your bot

   Find your bot on Telegram and send a message. You should get an ack and then a reply.

Features

Instant acknowledgment

When you send a message, the bot immediately replies with a random ack phrase (“Got it…”, “Cooking…”, “One sec…”). This is deleted once the real response arrives.

You can customize ack phrases in your agent’s encrypted secrets:

• ack_phrases — Full override (JSON array)
• ack_phrases_extra — Append to defaults (JSON array)

Typing indicator

During cold-start wait, the bot sends typing indicators to keep the conversation alive.

Deduplication

Messages are deduplicated by Telegram update_id via KV store (5-minute TTL). Telegram retries won’t cause duplicate processing.

Commands

Same commands work in Telegram:

Command	Effect
/clear	Start fresh session
/resume	List recent sessions
/model haiku	Switch models

Just type the command as a regular message.

Public demo bot

TinyFat runs a public demo bot (@GoTinyFatBot) powered by the ephemeral agent system:

• Each Telegram user gets their own isolated agent
• Rate limited to 20 messages/day
• The bot can block abusive users by writing to its system outbox
• Designed for onboarding — it explains TinyFat and directs users to sign up

Security

Webhook verification

Every webhook is verified using Telegram’s secret_token header. Invalid requests are rejected.

Token storage

Your Telegram bot token is encrypted at rest (AES-256-GCM), same as all secrets.

Troubleshooting

Bot not responding

1. Verify the bot token is correct in your dashboard
2. Check that the webhook is registered (dashboard should show status)
3. Try sending /start to the bot

Duplicate messages

Deduplication uses KV with 5-minute TTL. If you’re seeing duplicates, check that the queue isn’t retrying excessively.

Slow responses

First message after a long idle will trigger a cold start (~30-60s). Subsequent messages are faster (~10-20s).

Next steps

• Email Interface — Async email interface
• Slack Interface — Slack integration
• Web Chat — Real-time streaming