Skip to content
TinyFat Docs

Telegram

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

How it works

Section titled “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

Section titled “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

Section titled “Features”

Instant acknowledgment

Section titled “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

Section titled “Typing indicator”

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

Deduplication

Section titled “Deduplication”

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

Commands

Section titled “Commands”

Same commands work in Telegram:

CommandEffect
/clearStart fresh session
/resumeList recent sessions
/model haikuSwitch models

Just type the command as a regular message.

Public demo bot

Section titled “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

Section titled “Security”

Webhook verification

Section titled “Webhook verification”

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

Token storage

Section titled “Token storage”

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

Troubleshooting

Section titled “Troubleshooting”

Bot not responding

Section titled “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

Section titled “Duplicate messages”

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

Slow responses

Section titled “Slow responses”

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

Next steps

Section titled “Next steps”