Telego Bot Configuration Options Explained: A Complete Guide to Customizing Telegram Bots in Go

Telego provides flexible BotOption functions that configure HTTP clients, logging behavior, API endpoints, and health checks when passed to NewBot, allowing complete customization of your Telegram bot's initialization and runtime behavior.

The mymmrac/telego library offers a robust configuration system for building Telegram bots in Go. Through the NewBot constructor in bot.go, you can pass multiple BotOption functions—defined in bot_options.go—that modify the bot's internal state before it starts processing updates. This article explains every available Telego bot configuration option, their implementation details, and practical use cases for production and development environments.

HTTP Client Configuration Options

Telego allows you to customize the underlying HTTP transport layer, which is critical for controlling timeouts, connection pooling, TLS settings, and request execution strategies.

WithFastHTTPClient

The WithFastHTTPClient option replaces the default HTTP client with a fasthttp.Client instance for high-performance scenarios. According to bot_options.go (lines 23-29), this option instantiates ta.FastHTTPCaller{Client: client} and assigns it to bot.api.

Use this when you need reduced memory allocations and faster execution than the standard net/http package provides:

fastClient := &fasthttp.Client{
    MaxConnsPerHost: 100,
    ReadTimeout:     5 * time.Second,
}
bot, err := telego.NewBot(token, telego.WithFastHTTPClient(fastClient))

WithHTTPClient

The WithHTTPClient option accepts a standard *http.Client from the net/http package. As implemented in bot_options.go (lines 31-37), it wraps your client in ta.HTTPCaller{Client: client} and stores it in the bot's API field.

This is ideal when you have existing HTTP clients configured with custom transport layers, proxies, or retry logic:

httpClient := &http.Client{
    Timeout: 10 * time.Second,
    Transport: &http.Transport{
        Proxy: http.ProxyFromEnvironment,
    },
}
bot, err := telego.NewBot(token, telego.WithHTTPClient(httpClient))

WithAPICaller

For complete control over request execution, WithAPICaller allows you to provide a custom implementation of the ta.Caller interface. The implementation in bot_options.go (lines 15-21) directly assigns your caller to bot.api.

Use this for mocking API responses in unit tests or adding cross-cutting concerns like distributed tracing:

bot, err := telego.NewBot(token, telego.WithAPICaller(myCustomCaller))

Request Handling and API Configuration

These options modify how Telego constructs requests and which Telegram API endpoints it targets.

WithRequestConstructor

The WithRequestConstructor option swaps the default request builder with a custom ta.RequestConstructor implementation. According to bot_options.go (lines 39-45), this sets bot.constructor, allowing you to customize multipart form encoding or add default headers to all requests.

WithAPIServer

When using a self-hosted Telegram API proxy or the Bot API server, WithAPIServer overrides the default https://api.telegram.org base URL. The implementation in bot_options.go (lines 110-119) validates that the provided string is non-empty before setting bot.apiURL.

bot, err := telego.NewBot(
    token,
    telego.WithAPIServer("https://my-proxy.example.com"),
    telego.WithHealthCheck(context.Background()),
)

WithTestServerPath

For development and testing against Telegram's test environment, WithTestServerPath configures the bot to use the test API endpoint by setting bot.useTestServerPath = true (lines 122-131 in bot_options.go). This automatically appends /test/ to the API path structure.

bot, err := telego.NewBot(token, telego.WithTestServerPath())

Logging and Debug Configuration

Telego provides multiple strategies for observability, from silent discard loggers to verbose debug output with automatic token redaction.

WithDefaultLogger and WithExtendedDefaultLogger

WithDefaultLogger installs the library's built-in logger that automatically masks your bot token to prevent accidental credential exposure. As detailed in bot_options.go (lines 47-62), it creates a strings.Replacer that substitutes the token with [BOT_TOKEN] and configures both bot.log and bot.debugMode.

The WithExtendedDefaultLogger variant (lines 64-79) accepts your own *strings.Replacer for additional sensitive data redaction beyond the token.

// Basic setup: log errors only, hide token
bot, err := telego.NewBot(token, telego.WithDefaultLogger(false, true))

// Custom redaction: hide token and custom API keys
replacer := strings.NewReplacer(
    token, "[BOT_TOKEN]",
    apiKey, "[API_KEY]",
)
bot, err = telego.NewBot(token, telego.WithExtendedDefaultLogger(true, true, replacer))

WithDefaultDebugLogger and WithDiscardLogger

For rapid debugging, WithDefaultDebugLogger (lines 81-85) enables both debug and error output using the default logger. Conversely, WithDiscardLogger (lines 87-90) silences all log output by setting both flags to false, useful for production environments where external systems handle logging.

// Verbose debugging
bot, err := telego.NewBot(token, telego.WithDefaultDebugLogger())

// Silent operation
bot, err := telego.NewBot(token, telego.WithDiscardLogger())

WithLogger

When you need structured logging compatible with your existing observability stack, WithLogger (lines 92-100) accepts any implementation of the Logger interface defined by Telego. This allows integration with Zap, Logrus, or Zerolog.

zapLogger, _ := zap.NewProduction()
bot, err := telego.NewBot(
    token,
    telego.WithLogger(zap.NewStdLog(zapLogger)),
)

WithDebugMode

The WithDebugMode option (lines 102-108) enables detailed logging of request parameters by setting bot.debugMode = true. Unlike the default logger options, this exposes raw request data, meaning the bot token may appear in logs. Use this only for deep troubleshooting in secure environments.

bot, err := telego.NewBot(token, telego.WithDebugMode())

Operational and Health Configuration

These options affect runtime behavior, credential validation, and error handling policies.

WithHealthCheck

The WithHealthCheck option performs a GetMe request during bot initialization to validate the token and network connectivity. As implemented in bot_options.go (lines 133-146), it calls bot.GetMe(ctx) and caches the bot's ID and username in myID and myUsername fields. This provides fail-fast behavior for invalid tokens or unreachable networks.

bot, err := telego.NewBot(
    token,
    telego.WithHealthCheck(context.Background()),
)
if err != nil {
    log.Fatalf("health check failed: %v", err)
}

WithWarnings

By default, Telego treats Telegram API warnings (non-empty error fields in responses) as acceptable outcomes. The WithWarnings option (lines 148-155) enforces stricter error handling by setting bot.reportWarningAsErrors = true, causing warnings to be returned as Go errors.

bot, err := telego.NewBot(token, telego.WithWarnings())

How BotOption Functions Work Internally

Each BotOption is a function of type func(*Bot) error defined in bot_options.go. During NewBot construction in bot.go, the options are applied sequentially in the order provided. This design allows later options to override earlier ones, enabling composition patterns where you set defaults first and specific overrides last.

The functional options pattern provides compile-time safety and self-documenting code. Unlike configuration structs, you cannot misspell an option or provide invalid types—the compiler enforces correctness at build time.

Summary

• Telego bot configuration options are implemented as BotOption functions that modify the Bot struct during initialization via NewBot.
• HTTP client customization includes WithFastHTTPClient for high-performance fasthttp, WithHTTPClient for standard net/http, and WithAPICaller for complete request control.
• Logging options range from WithDefaultLogger (token-safe) to WithLogger (custom interface implementations), with specialized shortcuts like WithDefaultDebugLogger and WithDiscardLogger.
• Operational features include WithHealthCheck for startup validation, WithAPIServer for proxy configurations, WithTestServerPath for testing environments, and WithWarnings for strict error handling.
• Options are applied sequentially in bot_options.go, allowing later configurations to override earlier ones for flexible composition.

Frequently Asked Questions

What is the difference between WithFastHTTPClient and WithHTTPClient in Telego?

WithFastHTTPClient configures the bot to use fasthttp.Client, which offers reduced memory allocations and higher performance for high-throughput bots, while WithHTTPClient accepts a standard *http.Client from the net/http package. Choose WithFastHTTPClient when you need fine-grained control over timeouts and connections in production environments, and WithHTTPClient when integrating with existing HTTP infrastructure or requiring custom transport layers.

How does Telego protect my bot token from appearing in logs?

The WithDefaultLogger option in bot_options.go automatically creates a strings.Replacer that substitutes your bot token with the string [BOT_TOKEN] before any log output. This prevents accidental credential exposure during debugging. For additional security, WithExtendedDefaultLogger allows you to provide custom replacers to mask other sensitive data beyond the token.

Can I use a custom API server or proxy with Telego instead of the official Telegram API?

Yes, the WithAPIServer option allows you to override the default https://api.telegram.org base URL with any custom endpoint, such as a self-hosted Bot API server or a reverse proxy. Additionally, WithTestServerPath configures the bot to use Telegram's test environment by appending /test/ to the API path structure, which is useful for development and staging environments.

What happens if I enable WithHealthCheck during bot initialization?

When you pass WithHealthCheck(context.Background()) to NewBot, the constructor performs a synchronous GetMe request to the Telegram API before returning the bot instance. As implemented in bot_options.go (lines 133-146), this validates your token, verifies network connectivity, and caches the bot's ID and username in the myID and myUsername fields. If the health check fails, NewBot returns an error immediately, preventing your application from starting with invalid credentials.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}