This page explains how to configure a bot before calling NewBot(...). It focuses on BotOpts, environment-based configuration, and the practical meaning of the most important knobs.

Overview

BotOpts is the construction-time configuration object for Bot.

Use it when you want to control:

the Telegram token and API endpoint;
update types and command prefixes;
logging behavior;
request throttling behavior;
payload decoding strictness;
worker pool size.

The normal flow is:

create BotOpts manually, via LoadOptsFromEnv(), or via LoadBotOptsFile(...);
optionally refine it with setter methods;
pass it to NewBot(...).

For runtime configuration after bot creation, see Bot-Lifecycle.

Three ways to build `BotOpts`

Manual configuration

Use manual construction when settings are mostly static in code.

opts := (&laniakea.BotOpts{}).
	SetToken("TOKEN").
	SetPrefixes("/", "!").
	SetRateLimit(30).
	SetMaxWorkers(32)

Environment-based configuration

Use LoadOptsFromEnv() when your deployment environment should provide the values.

opts := laniakea.LoadOptsFromEnv()

bot, err := laniakea.NewBot[*App](opts)
if err != nil {
	return err
}

This is often the easiest approach for containers, CI, and production services.

File-based configuration

Use LoadBotOptsFile(...) when you want to keep bot configuration in a checked-in or deployment-managed config file.

Built in:

BotOptsFileJSONCodec for JSON files.

codec := laniakea.BotOptsFileJSONCodec{}
opts, err := laniakea.LoadBotOptsFile(codec, "config.json")
if err != nil {
	return err
}

bot, err := laniakea.NewBot[*App](opts)
if err != nil {
	return err
}

You can also persist BotOpts back to disk:

if err := laniakea.SaveBotOptsFile(codec, "config.json", opts); err != nil {
	return err
}

Before decoding, the loader expands placeholders like {{ TG_TOKEN }} from environment variables.

Only JSON support is built into the library right now. If you want another format, implement BotOptsFileCodec yourself. Use BotOptsFileJSONCodec as the reference implementation for custom codecs such as TOML.

Required setting

Only one field is strictly required:

Token

If Token is empty, NewBot(...) returns ErrTokenRequired.

Defaults worth knowing

Some important defaults are applied either by BotOpts loading helpers or by NewBot(...) itself:

Prefixes defaults to ["/"]
RateLimit defaults to 30
MaxWorkers defaults to 32
ErrorTemplate falls back to "%s" in the bot when unset
request logging and file logging are off by default
strict payload decoding is off by default

That means a very small config can still produce a usable bot.

Core fields

`Token`

Telegram bot token. Required.

Setter:

SetToken(token)

Env:

TG_TOKEN

`UpdateTypes`

Controls which update types the bot requests from Telegram.

If empty, Telegram may return all update types. Restricting this list can reduce noise and unnecessary processing when your bot only needs a subset.

Setter:

SetUpdateTypes(types...)

Env:

UPDATE_TYPES, semicolon-separated

Commands-and-Plugins

`Prefixes`

Defines command prefixes such as / or !.

Setter:

SetPrefixes(prefixes...)

Env:

PREFIXES, semicolon-separated

If unset, the default is /.

`ErrorTemplate`

Controls how returned handler errors are presented to users.

Example:

opts.SetErrorTemplate("Error\n\n%s")

Setter:

SetErrorTemplate(template)

Env:

ERROR_TEMPLATE

Error-Handling

Logging configuration

`Debug`

Enables debug-level logging.

Setter:

SetDebug(true)

Env:

DEBUG=true

`UseRequestLogger`

Enables request-level logging for Telegram API traffic.

Setter:

SetUseRequestLogger(true)

Env:

USE_REQ_LOG=true

`WriteToFile`

Enables file logging for bot and request logs.

Setter:

SetWriteToFile(true)

Env:

WRITE_TO_FILE=true

`LoggerBasePath`

Controls where log files are written when file logging is enabled.

Setter:

SetLoggerBasePath(path)

Env:

LOGGER_BASE_PATH

If unset, it defaults to ./.

API endpoint configuration

`UseTestServer`

Routes requests to Telegram's test server mode.

Setter:

SetUseTestServer(true)

Env:

USE_TEST_SERVER=true

Use this only for development and testing scenarios that explicitly target Telegram's test environment.

`APIURL`

Overrides the default Telegram API base URL.

Setter:

SetAPIURL(url)

Env:

API_URL

This is useful for:

proxies;
self-hosted gateways;
test infrastructure.

Rate limiting configuration

`RateLimit`

Controls the global request-per-second limiter used by the bot's Telegram API client.

Setter:

SetRateLimit(limit)

Env:

RATE_LIMIT

The default is 30.

`DropRLOverflow`

Switches the limiter into immediate rejection mode instead of waiting.

Setter:

SetDropRLOverflow(true)

Env:

DROP_RL_OVERFLOW=true

This is a policy decision:

false favors reliable delivery;
true favors responsiveness under overload.

Rate-Limiting

Payload decoding configuration

`StrictPayloadType`

Controls whether callback payload decoding accepts only the configured default payload type or tolerates other supported formats.

Setter:

SetStrictPayloadType(true)

Env:

STRICT_PAYLOAD_TYPE=true

Enable it when you want payload-type mismatches to fail loudly instead of being decoded permissively.

Inline-Keyboards-and-Payloads

Concurrency configuration

`MaxWorkers`

Controls the maximum number of update handlers that may run concurrently.

Setter:

SetMaxWorkers(workers)

Env:

MAX_WORKERS

Default:

32

Higher values can help I/O-heavy bots, but they also increase concurrency against your own dependencies such as databases and external APIs.

Bot-Lifecycle

Environment variables supported by `LoadOptsFromEnv()`

LoadOptsFromEnv() reads:

TG_TOKEN
UPDATE_TYPES
DEBUG
ERROR_TEMPLATE
PREFIXES
LOGGER_BASE_PATH
USE_REQ_LOG
WRITE_TO_FILE
USE_TEST_SERVER
API_URL
RATE_LIMIT
DROP_RL_OVERFLOW
STRICT_PAYLOAD_TYPE
MAX_WORKERS

List-valued fields use semicolon-separated values.

File placeholders supported by `LoadBotOptsFile()`

LoadBotOptsFile(...) expands placeholders in the form:

{{ TG_TOKEN }}
{{API_URL}}

Expansion happens before codec.FromBytes(...) is called.

This is useful when:

the config file structure should stay in version control;
secrets should still come from environment variables;
you want the same codec to work across local and deployed environments.

Recommended configurations

Minimal local setup

opts := (&laniakea.BotOpts{}).
	SetToken("TOKEN")

Typical production setup

opts := (&laniakea.BotOpts{}).
	SetToken(os.Getenv("TG_TOKEN")).
	SetPrefixes("/").
	SetRateLimit(30).
	SetMaxWorkers(32).
	SetErrorTemplate("Error\n\n%s")

More defensive callback setup

opts := (&laniakea.BotOpts{}).
	SetToken(os.Getenv("TG_TOKEN")).
	SetStrictPayloadType(true)

Recommendations

Start with the defaults unless you already know your traffic pattern.
Prefer LoadOptsFromEnv() for deployment-oriented apps.
Prefer LoadBotOptsFile(...) when you want structured config files or custom formats.
Set StrictPayloadType only when you are ready to enforce one payload encoding policy.
Increase MaxWorkers carefully and based on actual handler workload.
Turn on request logging selectively, because it is useful for debugging but noisy in normal operation.

Wiki

Bot Options and Configuration

Overview

Three ways to build BotOpts

Manual configuration

Environment-based configuration

File-based configuration

Required setting

Defaults worth knowing

Core fields

Token

UpdateTypes

Prefixes

ErrorTemplate

Logging configuration

Debug

UseRequestLogger

WriteToFile

LoggerBasePath

API endpoint configuration

UseTestServer

APIURL

Rate limiting configuration

RateLimit

DropRLOverflow

Payload decoding configuration

StrictPayloadType

Concurrency configuration

MaxWorkers

Environment variables supported by LoadOptsFromEnv()

File placeholders supported by LoadBotOptsFile()

Recommended configurations

Minimal local setup

Typical production setup

More defensive callback setup

Recommendations

Related pages

Navigation

Start here

Runtime and Architecture

Interaction and Telegram API

Practical Guides

Maintenance

Three ways to build `BotOpts`

`Token`

`UpdateTypes`

`Prefixes`

`ErrorTemplate`

`Debug`

`UseRequestLogger`

`WriteToFile`

`LoggerBasePath`

`UseTestServer`

`APIURL`

`RateLimit`

`DropRLOverflow`

`StrictPayloadType`

`MaxWorkers`

Environment variables supported by `LoadOptsFromEnv()`

File placeholders supported by `LoadBotOptsFile()`