Skip to content

Morsel Bots

Build bots for Morsel Chats. A bot is a key pair you run on your own server, end-to-end encrypted, with commands, buttons, payments, groups and inline mode.

Morsel Bots are programs that chat with people in Morsel. You run them on your own server, like a Telegram or Discord bot. Every message between a person and your bot is end-to-end encrypted: Morsel's servers only relay ciphertext.

Two SDKs do the work, and speak the same protocol byte for byte:

PackageLanguageInstall
@morsel/botTypeScript and JavaScript: Node 18 or later, Bun, Deno, edge runtimesnpm install @morsel/bot
morsel-botPython 3.10 or later, asynciopip install morsel-bot

Both live in one public repo, github.com/rugruts/morsel-bot, MIT licensed. If a package isn't on its registry yet, the quick starts show how to install it from GitHub.

What a bot is

  • A key pair. A bot is an ed25519 key pair, exactly like a wallet in Chats. Its address, the public key, is its id.
  • A token. The bot's token is its private key, written as text that starts with mbot1_. The Morsel app makes it on your phone and shows it once. Morsel's servers never see it.
  • A wallet. The bot's address is also a wallet on every network Morsel supports. People pay it there, and you can withdraw to your own wallet.
  • Self-hosted. Your server holds the token, encrypts and decrypts every message, and talks to the Morsel API. Morsel hosts nothing of yours.
  • No open port. By default the bot opens a connection out to Morsel and keeps it alive. You don't need a public IP or a domain. Signed webhooks are there for serverless platforms.

What a bot can do

  • Answer commands and text, with formatting: bold, italic, code, links, spoilers.
  • Show buttons under its messages: callbacks, links, mini apps, copy and pay buttons. Show reply buttons above the message box.
  • Edit its own messages for 48 hours, buttons included.
  • Ask for a payment and check it on chain before you count it.
  • Send and receive photos and files, end-to-end encrypted.
  • Join groups, with privacy mode so it only sees what is addressed to it.
  • Answer @yourbot query in any chat with text, photo and GIF results.

What a bot can't do

  • Start a conversation. A bot can only write to someone who wrote to it first and hasn't stopped it.
  • Write to other bots.
  • Manage groups. A bot can't create a group, add or remove people, or be an admin.
  • Read a whole group unless its owner turns privacy mode off, and the group is told.
  • Take payments. People always confirm a payment in their own wallet.

How it fits together

  1. You create the bot in the Morsel app and copy its token. See Create a bot.
  2. Your server runs the SDK with that token. The SDK signs every request with the bot's key.
  3. A person taps Start. Their app encrypts /start for the bot's address and sends the ciphertext to Morsel.
  4. Morsel delivers it to your bot over its live connection, or to your webhook.
  5. The SDK decrypts it, checks it, and runs your handler. Your reply goes back the same way.

Limits at a glance

Limit
Bots per owner20, and 5 new ones a day
Messages from a bot30 a second in all, about 1 a second per chat with bursts of 5, 20 a minute per group
Text in one message1000 characters
Edits48 hours, 100 edits a message
Inline answers30 seconds to answer, up to 50 results
Groups per bot5000

The reference has every limit and error code.

Next

Try one of these