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:
| Package | Language | Install |
|---|---|---|
@morsel/bot | TypeScript and JavaScript: Node 18 or later, Bun, Deno, edge runtimes | npm install @morsel/bot |
morsel-bot | Python 3.10 or later, asyncio | pip 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 queryin 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
- You create the bot in the Morsel app and copy its token. See Create a bot.
- Your server runs the SDK with that token. The SDK signs every request with the bot's key.
- A person taps Start. Their app encrypts
/startfor the bot's address and sends the ciphertext to Morsel. - Morsel delivers it to your bot over its live connection, or to your webhook.
- The SDK decrypts it, checks it, and runs your handler. Your reply goes back the same way.
Limits at a glance
| Limit | |
|---|---|
| Bots per owner | 20, and 5 new ones a day |
| Messages from a bot | 30 a second in all, about 1 a second per chat with bursts of 5, 20 a minute per group |
| Text in one message | 1000 characters |
| Edits | 48 hours, 100 edits a message |
| Inline answers | 30 seconds to answer, up to 50 results |
| Groups per bot | 5000 |
The reference has every limit and error code.
Next
- Create a bot in the app.
- Run an echo bot in five minutes: TypeScript or Python.
- Read Bot security before you go live.