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

> Explore Telego bot configuration options in Go. Customize HTTP clients logging API endpoints and health checks with BotOption functions for complete control over your Telegram bot.

- Repository: [Artem Yadelskyi/telego](https://github.com/mymmrac/telego)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/mymmrac/telego/blob/main/bot.go), you can pass multiple `BotOption` functions—defined in [`bot_options.go`](https://github.com/mymmrac/telego/blob/main/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`](https://github.com/mymmrac/telego/blob/main/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:

```go
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`](https://github.com/mymmrac/telego/blob/main/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:

```go
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`](https://github.com/mymmrac/telego/blob/main/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:

```go
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`](https://github.com/mymmrac/telego/blob/main/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`](https://github.com/mymmrac/telego/blob/main/bot_options.go) (lines 110-119) validates that the provided string is non-empty before setting `bot.apiURL`.

```go
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`](https://github.com/mymmrac/telego/blob/main/bot_options.go)). This automatically appends `/test/` to the API path structure.

```go
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`](https://github.com/mymmrac/telego/blob/main/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.

```go
// 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.

```go
// 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.

```go
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.

```go
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`](https://github.com/mymmrac/telego/blob/main/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.

```go
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.

```go
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`](https://github.com/mymmrac/telego/blob/main/bot_options.go). During `NewBot` construction in [`bot.go`](https://github.com/mymmrac/telego/blob/main/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`](https://github.com/mymmrac/telego/blob/main/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`](https://github.com/mymmrac/telego/blob/main/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`](https://github.com/mymmrac/telego/blob/main/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.