Your first bot in fiveĀ minutes

From nothing to a bot that answers /roll. You need a Mnema Talk server where you are the Owner or have Manage bots, and Node 24 or Go 1.26.

1. Create the bot

As the Owner, or as a member with Manage bots: Admin area > Bots > New bot, and give it a name. The bot gets two roles at once: the shared, managed Bot role and a role of its own, named after it. Both start with no permissions.

2. Let it see and write somewhere

Give the bot's own role the permissions it needs (for example View channels, Send messages, Add reactions) in the channels it should work in, through the channel permissions dialog. The bot's Access view in the Bots tab shows the effective result per channel.

3. Issue a token

In the bot's Tokens, issue one and copy it: it starts with mnb_ and is shown once. Only a hash is stored.

4. Call the API

export MNEMA=https://talk.example.orgexport TOKEN=mnb_...curl -s -H "Authorization: Bot $TOKEN" $MNEMA/api/bot/v1/users/@mecurl -s -H "Authorization: Bot $TOKEN" $MNEMA/api/bot/v1/channels

The first call returns the bot itself, the second the channels it can see. Post a message into one of them:

curl -s -X POST -H "Authorization: Bot $TOKEN" -H 'Content-Type: application/json' \
  -d '{"content": "build **passed**", "embeds": [{"title": "Run 42", "color": 65280}]}' \
  $MNEMA/api/bot/v1/channels/$CHANNEL_ID/messages

5. Answer /roll

Pick your language. Each program registers /roll, answers it, and stays connected.

TypeScript (Node 24 or newer)

A new project
mkdir roll-bot && cd roll-bot && npm init -y && npm pkg set type=modulenpm install @mnema-xyz/bot-sdk

Save this as bot.ts:

import { Client, OptionType } from '@mnema-xyz/bot-sdk'

const client = new Client({
  baseUrl: process.env.MNEMA_URL ?? '',
  token: process.env.MNEMA_TOKEN ?? '',
  intents: 0, // interactions need no intent
})

client.on('ready', async () => {
  await client.commands.set([
    {
      name: 'roll',
      description: 'Rolls a die',
      options: [{ name: 'sides', description: 'How many sides', type: OptionType.Integer, required: true }],
    },
  ])
  console.log(`online as ${client.user?.username}`)
})

client.on('interactionCreate', async (i) => {
  if (!i.isCommand() || i.commandName !== 'roll') return
  const sides = Number(i.options.get('sides'))
  const result = 1 + Math.floor(Math.random() * sides)
  await i.reply({ content: `${i.user.display_name} rolled **${result}** (d${sides})` })
})

client.on('error', (err) => console.error(err))
await client.connect()
MNEMA_URL=https://talk.example.org MNEMA_TOKEN=mnb_... node bot.ts

Go (1.26 or newer)

A new module
mkdir roll-bot && cd roll-bot && go mod init roll-botgo get github.com/mnema-xyz/bot-sdk-go@latest

Save this as main.go:

package main

import (
	"context"
	"fmt"
	"log"
	"math/rand/v2"
	"os"
	"os/signal"

	mnema "github.com/mnema-xyz/bot-sdk-go"
)

func main() {
	c, err := mnema.New(mnema.Options{BaseURL: os.Getenv("MNEMA_URL"), Token: os.Getenv("MNEMA_TOKEN")})
	if err != nil {
		log.Fatal(err)
	}
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()
	if _, err := c.REST.SetCommands(ctx, []mnema.CommandInput{{
		Name: "roll", Description: "Rolls a die",
		Options: []mnema.CommandOption{{Name: "sides", Description: "How many sides", Type: mnema.OptionInteger, Required: true}},
	}}); err != nil {
		log.Fatal(err)
	}
	c.OnInteraction(func(ctx context.Context, i *mnema.Interaction) {
		if i.CommandName() != "roll" {
			return
		}
		sides := i.Option("sides").Int()
		if sides < 2 {
			sides = 6
		}
		text := fmt.Sprintf("%s rolled **%d** (d%d)", i.User.DisplayName, rand.Int64N(sides)+1, sides)
		if err := i.Reply(ctx, mnema.Response{Content: text}); err != nil {
			log.Print(err)
		}
	})
	log.Fatal(c.Run(ctx))
}
MNEMA_URL=https://talk.example.org MNEMA_TOKEN=mnb_... go run .

6. Try it

Type / in a channel where the bot can view and send: /roll appears next to the built-in commands, with the bot's name and avatar. Run /roll sides: 20 and the bot answers.

Next: the concepts behind what you just did, then the recipes. Each SDK also ships three examples: TypeScript, Go.

Something wrong on this page? Tell us.