Skip to content

Bot security

The token is the bot's key and wallet. Keep it secret, keep the bot's balance low, regenerate a leaked token, protect webhooks, and never ask people for secrets.

A bot is a key pair. Whoever holds its key is the bot. Most of bot security follows from that.

The token is the key

The token is the bot's ed25519 seed. Anyone who has it can:

  • read the bot's chats, past and future;
  • write as the bot, to everyone who has talked to it;
  • move any funds at the bot's address.

So:

  • Keep it in an environment variable or your platform's secret store. On a server, a file readable only by root (chmod 600).
  • Keep it out of git, Docker images, logs, crash reports and anything that runs in a browser or an app.
  • Give it only to the process that runs the bot.

The SDKs never log the token, keys or message text. Text is logged only with debug: true in TypeScript or debug=True in Python. Use that on your own computer, never in production.

Keep the bot's balance low

People pay your bot at its address, and its key sits on a server. That makes it a hot wallet.

  • Keep only what you need there.
  • Withdraw regularly. Withdraw sends the balance to the wallet that owns the bot, a wallet whose key isn't on a server.

Regenerate a leaked token

If the token may have leaked, regenerate it at once: Settings → Chats → My bots → your bot → Regenerate token.

What happens:

  • The old key is refused from that moment: 401 BOT_REVOKED. Its live connections close.
  • The bot gets a new key, so a new address. Its username, profile, commands, webhook and settings stay.
  • People keep one chat with the bot. Their app moves to the new address by itself, shows the old messages above, and adds the line This bot moved to a new key.
  • A message still sent to the old address answers 410 BOT_MOVED with the bot's current address. The app resends it to the new one.
  • The new key can write to everyone who wrote to the old one.
  • Your bot is down until you put the new token on your server.

Funds at the old address stay under the old key, and whoever has the leaked token can move them. If you can, withdraw before you regenerate. Afterward, only the old token can move what's left there.

To stop a bot for good, Delete bot: every key it ever had is refused, and its username is free again after 30 days.

Webhooks

  • Use a long random secret, 16 to 128 characters: openssl rand -hex 32. Keep it next to the token, not in code.
  • Serve over https only.
  • Check the signature over the raw body before you parse anything. Refuse timestamps more than 5 minutes off. The SDK handlers do both. See Verify a webhook yourself.
  • Answer a delivery you've already handled with 2xx, without running it again.

Treat everything people send as untrusted

The SDKs check each payload against the row Morsel delivered: same sender, same recipient or group, same client id. They drop unknown fields, cap every field's length, and refuse group messages whose signature doesn't hold. Still:

  • Treat ctx.text, command arguments, /start payloads and callback data as untrusted input.
  • Credit payments only from the payment event, which the SDK checked on chain. Never from text, a screenshot or a pasted signature.
  • Record each payment's signature in your own database, and never deliver twice for one.

Never ask for secrets

A bot must never ask people for their Secret Recovery Phrase, password or private keys. Morsel tells people never to share them with a bot, and people can report bots that spam or scam. Morsel can suspend a bot.

What you're responsible for

Messages are end-to-end encrypted between each person and your bot. Morsel's servers can't read them. Your server can. You are responsible for what it stores and for keeping it safe. Ask for and keep only what your bot needs.

Try one of these