Bot API

How bots work

There is no separate bot server or HTTP API to call. The Jaw.Bots library does in your process everything a Jaw app does: it holds the bot's keys, connects to a home node over a WebSocket, encrypts and decrypts messages, and keeps the bot's rooms in sync. Nodes only ever carry the bot's ciphertext, exactly as they do for people.

• A bot is a declared account. It publishes a signed bot profile: its name, description, the permissions it asks for and its slash commands. Apps show a BOT tag beside it and list it in the bot directory (Browse → Find a bot).
• Rooms choose to add it. A room operator adds the bot from an approval screen that lists what it asks for, and may grant less. The bot then gets a role with those permissions and joins by itself.
• Commands are addressed to it. When someone types /roll 2d6 and picks your bot's command, the app sends a signed command event to the room that only your bot answers.
• Buttons are just labels and ids. Nothing runs in people's apps. A click is posted to the room as a signed event, and your handler decides what happens.

Get the SDK

You need the .NET 10 SDK (dot.net). The bot kit contains:

To use the SDK in your own project, put your project inside the unzipped kit folder (so it finds nuget.config), or add packages/ as a package source, then:

dotnet new console -n MyBot
cd MyBot
dotnet add package Jaw.Bots --version 0.0.5

Quick start

The smallest useful bot: one command, run until Ctrl+C.

using Jaw.Bots;

using var stop = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => { e.Cancel = true; stop.Cancel(); };

await using var bot = new JawBot(new JawBotOptions
{
    DataDirectory = "mybot-data",   // its keys live here: keep it private, back it up
    Name = "MyBot",
    Description = "Says hello.",
    OnRecoveryPhrase = words => Console.WriteLine("Recovery phrase: " + string.Join(' ', words)),
});

bot.Command("hello", "Say hello", ctx => ctx.ReplyAsync($"Hello, {ctx.UserName}!"));

await bot.RunAsync(stop.Token);

Register every command and handler before calling RunAsync; it throws if you add one after. RunAsync returns when the token is cancelled.

First run and adding your bot to a room

1. Account. On the first run the bot creates its account in DataDirectory and calls OnRecoveryPhrase once with its 24-word recovery phrase. The SDK never stores or logs the phrase: write it down if you want to be able to recover the bot.
2. Home node. If you set Node, it connects there. Otherwise it uses the node it used last time, or picks one from the network's starting list that ships inside the package. A node picked from that list must prove it is the node the list names. To use this node:

   Node = new Uri("wss://chronocloned.net/ws/client"),

3. Declare. It publishes its bot profile (only when something in it changed) and, if you set Handle, claims that @handle so people can find it.
4. Add it to a room. In a Jaw app, open Browse → Find a bot, or invite the bot's @handle from a room. The room operator sees what the bot asks for, chooses what to grant, and the bot joins by itself (set AcceptInvites = false to turn that off).
5. Use it. Type / in the room to see its commands.

Bots for one community

Not every bot is for everyone. If you've built a bot for your own server, set Listed = false and give it a handle:

await using var bot = new JawBot(new JawBotOptions
{
    DataDirectory = "denbot-data",
    Name = "DenBot",
    Description = "Rota and reminders for the Den.",
    Handle = "denbot",
    Listed = false,   // don't advertise it
});

An unlisted bot:

• doesn't appear in bot search (Browse → Find a bot, or a node's /api/bots);
• can't be featured by node owners, and leaves the featured list if it was featured before;
• still works everywhere else. Invite it from your room by its handle (@denbot): the room operator gets the usual approval screen, and its commands and buttons work as normal.

Unlisted isn't secret. Its profile still travels between nodes so every member's app can show its commands, and anyone who knows its handle or id can look it up. It just isn't advertised. You can change your mind at any time: set Listed back to true and restart the bot.

Your bot's home node must support unlisted bots. If it doesn't, RunAsync stops with a BotException saying so, rather than publishing the bot as listed. Choose a newer node with Node. Nodes that haven't updated yet never receive unlisted profiles, so people whose home node is one of those see the bot as an ordinary account until their node updates.

Options

JawBotOptions: only DataDirectory and Name are required.

Slash commands

bot.Command(name, description, handler, params BotCommandOption[] options)

Names are 1-32 characters of a-z 0-9 _ -. Descriptions are shown in the command list (up to 100 characters). A bot can have up to 50 commands, each with up to 10 options.

Options are matched to what the person typed, in order, split on spaces; the last option gets the rest of the line. Declare one with new BotCommandOption(name, description, required).

using Jaw.Core.Bots;

bot.Command("remind", "Remind the channel later, e.g. /remind 10 stand up", async ctx =>
{
    if (!int.TryParse(ctx.Option("minutes"), out var minutes) || minutes is < 1 or > 1440)
    {
        await ctx.ReplyAsync("Say how many minutes, e.g. /remind 10 stand up");
        return;
    }

    var what = ctx.Option("what") ?? "something";
    await ctx.ReplyAsync($"OK, I'll remind you in {minutes} min.");
    _ = RemindLaterAsync(ctx.Bot, ctx.Room, ctx.Channel, minutes, what);   // don't hold up other events
},
new BotCommandOption("minutes", "How long to wait", true),
new BotCommandOption("what", "What to say", false));

static async Task RemindLaterAsync(JawBot bot, Jaw.Core.Rooms.RoomId room, string channel, int minutes, string what)
{
    await Task.Delay(TimeSpan.FromMinutes(minutes));
    await bot.SendAsync(room, channel, "⏰ " + what);
}

In the handler, CommandContext gives you:

Buttons and menus

Pass components to ReplyAsync or SendAsync. Apps draw them only on messages from declared bots.

using Jaw.Core.Rooms;

await ctx.ReplyAsync("Deploy to production?",
    MessageComponent.Button("deploy:yes", "Deploy", ButtonStyle.Danger),
    MessageComponent.Button("deploy:no", "Cancel"));

await ctx.ReplyAsync("Pick a colour",
    MessageComponent.Select("colour", "Choose…",
    [
        new SelectOption("red", "Red"),
        new SelectOption("green", "Green"),
        new SelectOption("blue", "Blue"),
    ]));

• MessageComponent.Button(id, label, style): styles are Primary, Secondary (the default) and Danger.
• MessageComponent.Select(id, placeholder, options): a menu of up to 25 SelectOption(value, label) choices, each value unique and up to 100 characters.
• Ids are 1-32 characters of a-z 0-9 _ - : .. Use a prefix such as poll: so one handler can take a family of buttons.
• Up to 10 components per message; labels up to 80 characters.

Handling clicks

bot.OnInteraction("deploy:", async click =>
{
    if (click.ComponentId == "deploy:yes")
    {
        await click.EditMessageAsync($"Deploying (asked by {click.UserName})…");
        // … start the deploy …
    }
    else
    {
        await click.EditMessageAsync("Cancelled.");
    }
});

bot.OnInteraction("colour", click => click.ReplyAsync($"{click.UserName} picked {click.Value}."));

OnInteraction(prefix, handler) runs for clicks on components whose id starts with the prefix; OnInteraction(handler) runs for every click. Only clicks on your bot's own messages reach it. InteractionContext has the same User, Room, Channel and SendAsync as commands, plus:

Anyone in the room can click, as many times as they like: decide in your handler who may do what (for example, only the person who ran the command), and count one vote per User.

Reading room messages

bot.OnMessage(async msg =>
{
    if (msg.Text.Contains("http://", StringComparison.OrdinalIgnoreCase))
    {
        await msg.Bot.SendAsync(msg.Room, msg.Channel, $"{msg.UserName}, please share https links.");
    }
});

OnMessage gets ordinary messages in rooms the bot is in, from other people, sent after the bot started. MessageContext has Text, Message, the usual User, Room and Channel, and DeleteAsync() (which needs the Delete other people's messages permission). A bot that reads chat can read everything in the channels it is in, so say so in its Description.

Direct messages

bot.OnDirectMessage(dm => dm.ReplyAsync($"Hi {dm.FromName}! Add me to a room and type /help there."));

// Or start one yourself:
await bot.SendDirectAsync(someUserId, "Your report is ready.");

DirectMessageContext has From (a UserId), FromName, Text and ReplyAsync(text).

Doing things on your own

Outside a handler, use the JawBot methods with a room id you got from a context or from bot.Rooms. Room ids can be saved as text (room.ToString()) and read back with RoomId.Parse(text).

// Post to every room the bot is in, e.g. from a timer.
foreach (var room in bot.Rooms)
{
    await bot.SendAsync(room, "main", "Good morning! ☀️");
}

await bot.EditAsync(room, messageId, "New text");    // the bot's own messages
await bot.DeleteAsync(room, messageId);             // its own, or others' with the permission
await bot.JoinPublicRoomAsync(RoomId.Parse(text));   // a public room listed on the bot's home node

Anything the room or node refuses throws a BotException whose message says why (for example, the bot may not send in that channel). Calling these before RunAsync has started throws InvalidOperationException.

Permissions

Set RequestedPermissions to what your bot needs, combined with |, and ask for as little as you can: operators are shown the list, and may grant less. Most bots need only SendMessages.

RequestedPermissions = RoomPermissions.SendMessages | RoomPermissions.ManageMessages,

"Per channel" permissions can be changed for one channel by the room's operators, so a bot may be able to speak in one channel and not another.

How events are delivered

• One at a time, in order. Handlers never run at the same time, so you don't need locks for state only handlers touch. Keep them quick: start long work without awaiting it (as in the /remind example) so other events aren't held up. Calling the bot's methods from your own tasks and timers is fine too.
• Bounded. Up to 1,000 events wait in line; if your handlers fall further behind, the oldest are dropped.
• Once each. Each event reaches your handlers once, even if it arrives again after a reconnect.
• Not stale. Commands and clicks older than MaxEventAge are skipped, so a bot that was offline doesn't answer an hour-old /roll. Room messages are delivered only from when the bot started.
• Failures are contained. An exception in a handler is logged and the bot carries on.
• Reconnects by itself. If the connection drops, it reconnects with a growing delay, and catches up on rooms and direct messages when it's back.

Limits

Nodes may also rate-limit busy senders; bots get higher limits than people.

Keeping your bot safe

• The data folder is the account. Anyone with a copy of DataDirectory can act as your bot. Keep it readable only by the bot's user, back it up, and never commit it to source control.
• Prefer a passphrase from a secret store (Passphrase), so a copy of the disk alone isn't enough.
• Keep the recovery phrase offline. It can rebuild the account if the folder is lost.
• Don't log what people write. The SDK logs ids only, never message contents or keys; keep your own logging the same way.
• Treat input as untrusted. Command options, menu values and messages come from anyone in the room. Check them before using them, especially before running anything or calling another service.
• Ask for little. Request only the permissions you use.

Logging

Pass any ILogger<JawBot> (from Microsoft.Extensions.Logging) as the second argument: new JawBot(options, logger). Event ids:

With the generic host you can inject it: services.AddLogging() then provider.GetRequiredService<ILogger<JawBot>>().

Running it for real

Publish it and run it as a service. On Linux with systemd:

dotnet publish -c Release -o /opt/mybot

# /etc/systemd/system/mybot.service
[Unit]
Description=MyBot (Jaw bot)
After=network-online.target

[Service]
User=mybot
WorkingDirectory=/var/lib/mybot
ExecStart=/usr/bin/dotnet /opt/mybot/MyBot.dll
Environment=JAW_BOT_DATA=/var/lib/mybot/data
Restart=on-failure

[Install]
WantedBy=multi-user.target

Run one copy per data folder. The bot's account can be used from a limited number of devices, and each data folder is one device.

API reference

JawBot

Contexts

Common members (room contexts): Bot, Room, RoomName, Channel, User, UserName, SendAsync(text), SendAsync(text, components...).

Namespaces

Jaw.Bots (the bot, options, contexts, BotException), Jaw.Core.Bots (BotCommandOption), Jaw.Core.Rooms (RoomId, RoomPermissions, MessageComponent, ButtonStyle, SelectOption), Jaw.Core.Identity (UserId).

Full example: DiceBot

The example in the bot kit (DiceBot/Program.cs): dice, a coin and yes/no polls with live tallies. The main part:

var options = new JawBotOptions
{
    DataDirectory = Environment.GetEnvironmentVariable("JAW_BOT_DATA") ?? "dicebot-data",
    Name = "DiceBot",
    Description = "Rolls dice, flips coins and runs quick yes/no polls.",
    Developer = "Jaw example",
    Tags = ["games", "polls"],
    RequestedPermissions = RoomPermissions.SendMessages,
    Handle = Environment.GetEnvironmentVariable("JAW_BOT_HANDLE"),
    Node = Environment.GetEnvironmentVariable("JAW_NODE") is { Length: > 0 } node ? new Uri(node) : null,
    OnRecoveryPhrase = words => Console.WriteLine("Recovery phrase: " + string.Join(' ', words)),
};

await using var bot = new JawBot(options, new ConsoleLogger());
var polls = new ConcurrentDictionary<string, Poll>();

bot.Command("roll", "Roll dice, e.g. /roll 2d6", async ctx =>
{
    if (!Dice.TryParse(ctx.Option("dice") ?? "1d6", out var count, out var sides))
    {
        await ctx.ReplyAsync("Try something like /roll 2d6 (up to 20 dice with up to 1000 sides).");
        return;
    }

    var rolls = Enumerable.Range(0, count).Select(_ => RandomNumberGenerator.GetInt32(1, sides + 1)).ToList();
    var detail = rolls.Count == 1 ? "" : $"{string.Join(" + ", rolls)} = ";
    await ctx.ReplyAsync($"🎲 {ctx.UserName} rolled {count}d{sides}: {detail}{rolls.Sum()}");
}, new BotCommandOption("dice", "How many and which, e.g. 2d6", false));

bot.Command("coin", "Flip a coin", ctx => ctx.ReplyAsync(RandomNumberGenerator.GetInt32(2) == 0 ? "🪙 Heads" : "🪙 Tails"));

bot.Command("poll", "Ask a yes/no question", async ctx =>
{
    await ctx.ReplyAsync(Poll.Render(ctx.Option("question") ?? "", 0, 0),
        MessageComponent.Button("poll:yes", "Yes", ButtonStyle.Primary),
        MessageComponent.Button("poll:no", "No"));
}, new BotCommandOption("question", "What to ask", true));

// One vote per person; voting again moves it.
bot.OnInteraction("poll:", async click =>
{
    var poll = polls.GetOrAdd(Convert.ToHexString(click.Message.Id), _ => new Poll(click.Message.Text));
    poll.Vote(click.User.ToString(), click.ComponentId == "poll:yes");
    await click.EditMessageAsync(Poll.Render(poll.Question, poll.Yes, poll.No));
});

bot.OnDirectMessage(dm => dm.ReplyAsync("Hi! Add me to a room and type /help there."));

await bot.RunAsync(stop.Token);

Run it from the kit with cd DiceBot then dotnet run. Settings come from JAW_BOT_DATA, JAW_NODE and JAW_BOT_HANDLE.

Troubleshooting