Skip to content

BotFlux

BotFlux is a Java framework for building dialog systems and chat bots that run across multiple channels (Telegram, VK, Web, and others) on a shared core.

BotFlux allows you to implement business logic faster than working directly with messenger SDKs, while preserving a strict architecture, testability, and long-term scalability.

What is BotFlux

BotFlux is not an SDK for a specific messenger and not a low-code builder with rigid limitations.

It is a runtime and architectural layer that:

  • isolates business logic from concrete message delivery channels
  • provides a unified component lifecycle
  • allows the same code to run across multiple channels without rewriting logic
  • ensures component interchangeability (for example, selecting or replacing a JSON serializer, cache, HTTP transport, or other infrastructure components without affecting business logic)

Key concepts

  • Separation of responsibilities

The Gateway is responsible for integration with the external world, while the Dispatcher handles events and business logic.

  • Abstract actions and events

Sending messages, buttons, and media is expressed through actions, while receiving messages, button clicks, and other user interactions is represented as events, without direct calls to messenger-specific APIs.

  • Unified lifecycle

All components are managed centrally and are started and stopped in a controlled and consistent manner.

  • Abstract media

Photos, videos, audio, voice messages, and video notes are represented by a single BotMedia type, which can be received and sent, as well as read from and written to disk in a reactive manner based on Flux<ByteBuffer>.

  • Minimal startup with fine-grained control

The bootstrap process automatically discovers components via ServiceLoader, allowing a minimal project to run without additional configuration, while still enabling explicit configuration and replacement of any component when needed.

  • Graceful shutdown

Controlled shutdown with configurable timeouts is supported to complete event processing without message loss.

  • Coordinated execution

BotFlux guarantees coordinated operation of all gateways; if one gateway fails, BotFlux gracefully stops the others.

Minimal example

A simple text echo bot with a single gateway:

BotFluxBootstrap.go()
    .autoInfrastructure() // (1)!

    .dispatcherProvider(PipelineDispatcherProviderBuilder.builder() // (2)!
        .methodHandlerFlow(flow -> flow
            .when(n -> n // (3)!
                .into(BotFlowUtil::getText) // (4)!
                .then(BotFlowUtil::sendText)) // (5)!
            .execute()) // (6)!
        .build())

    .gateway(telegram() // (7)!
        .token(System.getenv("TELEGRAM_TOKEN")) // (8)!
        .intent())
    .commit() // (9)!

    .create() // (10)!

    .start(); // (11)!
  1. automatic infrastructure component selection
  2. business logic
  3. option
  4. has text?
  5. echo it back
  6. end of options
  7. Telegram gateway
  8. Telegram token from environment
  9. finalize gateways
  10. create BotFlux
  11. start BotFlux

In this example:

  • Telegram is used as the delivery channel
  • the logic does not depend on the Telegram API
  • the same dispatcher can be launched with a different gateway without changes (add another .gateway(...) before calling .commit())

What you get out of the box

  • a unified runtime for multiple channels
  • clear contracts between system layers
  • a reactive event processing model
  • a centralized component lifecycle
  • graceful shutdown support

Usage levels

BotFlux does not enforce a single development style:

  • Quick start

Minimal code, simple lambda-based handlers, fast results.

  • Structured logic

Multiple gateways, state management, virtual URIs (for MVC-style organization of logic), reusable scenarios.

  • Full control

Configuration of infrastructure components (SSL, proxy, caching policies), custom components (HTTP/WS transport, serializer, cache), gateways for custom platforms.

Where to go next

  • Quick Start — launch your first browser-based bot in minutes
  • Concepts — an overview of BotFlux internals
  • Gateways — supported channels and their specifics
  • Testing — testing bots and business logic