BotLib 2.1.1-pre

BotLib

BotLib is a .NET library for building Telegram bots around a finite-state-machine flow.

The library wraps Telegram.Bot and adds three main concepts:

• TelegramFsmBot: the bot runtime, update dispatcher, and Telegram client.
• BotMachine: per-user session state holder.
• BotState: a single dialog state that receives commands and produces outgoing messages.

The repository also contains TestConsoleApp, a minimal runnable example of a bot built on top of the library.

Target Framework

• .NET 10

What the Component Does

BotLib is intended for bots where user interaction is modeled as a sequence of states:

• a user sends a Telegram update;
• the update is converted into a command such as text, callback button press, file, photo, or geo;
• the command is routed to that user's BotMachine;
• the active BotState processes the command;
• the state emits one or more outgoing messages and may switch to another state.

This is useful for:

• guided chat flows;
• menu-based bots;
• multi-step forms;
• bots that need separate dialog state per user.

Architecture

TelegramFsmBot

Base class for the bot itself.

Responsibilities:

• starts Telegram polling;
• receives Telegram updates;
• converts updates into TelegramCommand objects;
• creates and destroys per-user BotMachine instances;
• queues outgoing messages through TelegramMessageSender;
• exposes integration events such as payments, parametric /start, and large-file handling.

Main file:

• BotLib/Engine/TelegramFsmBot.cs

BotMachine

Represents one user session.

Responsibilities:

• owns the current ActiveState;
• forwards commands to the active state;
• switches states when the current state emits StateIsChanged;
• keeps the last sent Telegram message id;
• passes generated messages to the sender queue.

Main file:

• BotLib/Fsm/BotMachine.cs

BotState

Base class for a single state in the dialog.

Responsibilities:

• initializes UI/message output in Init();
• handles incoming commands in ProcessCommand();
• emits messages with PostMessage() and PostNonPriorityMessage();
• switches to another state with ActivateState().

Main file:

• BotLib/Fsm/BotState.cs

Command Model

Incoming Telegram updates are converted to strongly-typed command objects, for example:

• TelegramTextCommand
• TelegramButtonPressedCommand
• TelegramPhotoCommand
• TelegramFileCommand
• TelegramGeoCommand

Main files:

• BotLib/Engine/Commands

Message Model

States do not call Telegram API directly. Instead, they create message objects that are sent by the internal sender queue.

Examples:

• TelegramTextMessage
• TelegramTextMessageWithKeyboard
• TelegramTextMessageWithKeyboardEdited
• TelegramPictureMessage
• TelegramFileMessage
• TelegramPaymentMessage
• TelegramTypingMessage

Main files:

• BotLib/Engine/Messages

Minimal Usage

1. Create a bot class

Inherit from TelegramFsmBot, pass the machine type and initial state types into the base constructor, and start receiving updates.

using BotLib.Engine;
using BotLib.Engine.Commands;
using System.Net.Http;

internal class DemoBot : TelegramFsmBot
{
    public DemoBot(string token, HttpClient? httpClient = null)
        : base(
            token,
            typeof(DemoFirstState),
            typeof(DemoFirstState),
            typeof(DemoMachine),
            httpClient)
    {
        StartReceiving();
    }

    public override bool PerformPreCheckoutQuery(string invoiceId, ref string oopsAnswer)
    {
        return true;
    }

    protected override bool IsException(TelegramCommand command)
    {
        return false;
    }
}

Real example:

• TestConsoleApp/TestBot.cs

2. Create a machine class

Usually this class is small and just passes dependencies into the base constructor.

using BotLib.Engine;
using BotLib.Fsm;
using System;

internal class DemoMachine : BotMachine
{
    public DemoMachine(long userId, TelegramMessageSender sender, Type initStateType, TelegramFsmBot bot)
        : base(userId, sender, initStateType, bot)
    {
    }
}

Real example:

• TestConsoleApp/TestMachine.cs

3. Create a state

State initialization sends the first message. Command handling updates the flow.

using BotLib.Engine.Commands;
using BotLib.Engine.Messages;
using BotLib.Fsm;

internal class DemoFirstState : BotState
{
    private const string IncrementCallback = "increment";
    private TelegramTextMessageWithKeyboard activeMessage;
    private int counter = 1;

    public DemoFirstState(long userId, BotMachine machine) : base(userId, machine)
    {
    }

    public override void Init()
    {
        activeMessage = new TelegramTextMessageWithKeyboard(UserId, $"Counter: {counter}");
        activeMessage.AddCallbackButton("Increment", IncrementCallback);
        PostMessage(activeMessage);
    }

    public override void ProcessCommand(TelegramCommand command)
    {
        if (command is TelegramButtonPressedCommand button &&
            button.CallbackData == IncrementCallback)
        {
            counter++;
            PostMessage(new TelegramTextMessage(UserId, $"Counter: {counter}"));
        }
    }
}

Real example:

• TestConsoleApp/TestFirstState.cs

Running the Example

1. Put your bot token into apikey.txt in the TestConsoleApp working directory.
2. Build the solution:

dotnet build BotLib.slnx

3. Run the sample app:

dotnet run --project TestConsoleApp/TestConsoleApp.csproj

Entry point:

• TestConsoleApp/Program.cs

Included Features

• per-user machine lifecycle;
• typed commands for text, callbacks, files, photos, and geo;
• queued message sending;
• inline keyboard helpers;
• message editing helpers;
• payment pre-checkout handling;
• admin-task queue support;
• parametric /start xxx handling;
• file-too-large event hook.

Repository Layout

BotLib/
  BotLib/
    Engine/
      AdminTasks/
      Commands/
      Exceptions/
      Messages/
    Fsm/
      HelperStates/
      FsmEventArgs/
  TestConsoleApp/

Notes

• BotLib currently derives directly from TelegramBotClient.
• The library contains a compatibility layer for newer Telegram.Bot APIs in BotLib/Engine/TelegramBotClientCompatExtensions.cs.
• Package generation is enabled in BotLib/BotLib.csproj, so build also produces NuGet packages.

License

MIT