Skip to content

Bot quick start in TypeScript

Run an echo bot for Morsel Chats on your own computer with @morsel/bot, Node and a token from the app, in about five minutes.

You'll run a bot that answers /start and repeats what people send it. It runs on your computer and connects out to Morsel, so you don't need a domain or an open port.

You need Node 18 or later and a bot token. To get one, see Create a bot.

1. Make a project

Terminal
mkdir my-bot && cd my-bot
npm init -y
npm pkg set type=module
npm install @morsel/bot
npm install --save-dev tsx

The SDK ships ESM and CommonJS builds with types. Its only dependencies are @noble/curves, @noble/hashes and @noble/ciphers.

If npm can't find @morsel/bot

Then it isn't on npm yet. Build it from the GitHub repo instead, next to your project:

Terminal
cd ..
git clone https://github.com/rugruts/morsel-bot
cd morsel-bot/typescript
npm install && npm run build && npm pack
cd ../../my-bot
npm install ../morsel-bot/typescript/morsel-bot-0.1.0.tgz

npm pack prints the file it wrote. Use that name if the version differs.

2. Write the bot

bot.ts
import { Bot, FileStore } from '@morsel/bot';

const bot = new Bot(process.env.MORSEL_BOT_TOKEN!, {
  // Remembers where the bot got to, so a restart catches up instead of missing messages.
  store: new FileStore('bot.json'),
});

bot.command('start', (ctx) => ctx.reply('Hi! Send me anything and I will send it back.'));

bot.on('message', async (ctx) => {
  if (!ctx.text) return ctx.reply('I only echo text.');
  await ctx.reply(ctx.text, { entities: ctx.message?.entities, replyTo: true });
});

bot.catch((err) => console.error('A handler failed:', (err as Error).message));

await bot.start({
  onStart: ({ address, username }) => console.log(`Running as @${username} (${address})`),
});

Handlers run in the order you register them, and the first one that matches handles the message. That's why /start goes to the command handler, and everything else to the echo.

3. Run it

Terminal
export MORSEL_BOT_TOKEN='mbot1_...'
npx tsx bot.ts

Paste your own token. On Windows PowerShell, use $env:MORSEL_BOT_TOKEN='mbot1_...'.

The bot prints its username and address, then waits. Leave it running.

4. Talk to it

  1. In Morsel, open Chats and search for your bot's @username.
  2. Tap Start. The bot says hi.
  3. Send it anything. It replies with the same text.

Stop the bot with Ctrl+C. Messages sent while it's down wait for it: when it starts again, it catches up from bot.json.

Plain JavaScript

Save the same code as bot.mjs, remove the ! after the token and the as Error, and run node bot.mjs.

If it doesn't work

What you seeWhat to do
TokenError when it startsThe token is incomplete or mistyped. Copy it again from where you saved it.
It stops with BOT_REVOKEDThe token was regenerated. Use the new one.
It stops with BOT_SUSPENDEDMorsel suspended the bot. It can't send or receive messages.
The bot answers twiceTwo copies are running with the same token. Run one.
Nothing arrivesMake sure you messaged the right @username, and that the bot printed its address.

Next

Try one of these