# How to Initialize a Telego Bot with a Token: A Complete Guide

> Learn to initialize a Telego bot with a token using telego.NewBot(). This guide shows how to create a configured *Bot instance for your Telegram application.

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

---

**Initializing a Telego bot requires passing a valid Telegram bot token to `telego.NewBot()`, which validates the token format and returns a configured `*Bot` instance that you can enhance with functional options like debug loggers or custom HTTP clients.**

The `mymmrac/telego` library provides a robust Go interface to the Telegram Bot API. When you initialize a Telego bot with a token, the constructor handles validation, sets up default components for HTTP communication, and applies any customization options you provide. This process ensures your bot is ready to send and receive messages immediately after initialization.

## Understanding the NewBot Constructor

The `NewBot` function in [`main/bot.go`](https://github.com/mymmrac/telego/blob/main/main/bot.go) serves as the primary entry point for bot initialization. It implements a functional options pattern that allows flexible configuration while enforcing strict token validation.

### Token Validation

Before allocating any resources, `NewBot` invokes the internal `validateToken` function to verify that your token matches Telegram's required format. The validation uses the regular expression `^\d+:[\w-]{35}$`, which ensures the token consists of numeric digits, a colon, and exactly 35 alphanumeric characters or hyphens. This check occurs at lines 39-44 in [`main/bot.go`](https://github.com/mymmrac/telego/blob/main/main/bot.go).

### Default Components

Once validation passes, the constructor allocates a `Bot` struct with sensible defaults:

- **Token**: The validated token string
- **API Server URL**: `https://api.telegram.org`
- **Logger**: A default logger that masks the token for security (`newDefaultLogger`)
- **HTTP Caller**: `FastHTTPCaller` for high-performance requests
- **Request Constructor**: `ta.DefaultConstructor` for building API payloads

This initialization happens in the struct literal at lines 101-107 of [`main/bot.go`](https://github.com/mymmrac/telego/blob/main/main/bot.go).

### Applying Bot Options

After establishing defaults, `NewBot` iterates through all provided `BotOption` functions and applies them sequentially. This loop at lines 109-113 allows you to override any default component, such as replacing the HTTP client or enabling debug logging.

## Token Requirements and Validation

Telegram bot tokens follow a strict format that Telego enforces during initialization. The token must:

1. Start with numeric digits representing the bot ID
2. Contain a colon separator
3. End with exactly 35 characters consisting of letters, numbers, or hyphens

If your token fails this validation, `NewBot` returns an error immediately, preventing initialization with malformed credentials. This validation logic is defined in [`main/bot.go`](https://github.com/mymmrac/telego/blob/main/main/bot.go) within the `validateToken` helper function.

## Configuration Options for Initialization

The [`bot_options.go`](https://github.com/mymmrac/telego/blob/main/bot_options.go) file defines the `BotOption` type and numerous helper functions that customize bot behavior during initialization. These options use the functional options pattern to keep the API clean while providing extensive flexibility.

### Debug Logging

The `WithDefaultDebugLogger()` option replaces the default token-masking logger with one that prints detailed request and response information. This is essential during development for troubleshooting API interactions.

### Custom HTTP Clients

You can replace the default `FastHTTPCaller` with alternative implementations using either `WithAPICaller(customCaller)` for complete control over the HTTP layer, or `WithHTTPClient(customHTTPClient)` for simpler cases where you only need to adjust timeouts or transport settings.

### Custom API Servers

The `WithAPIServer(url)` option redirects requests to a custom Telegram Bot API server instance. This is useful when running the Bot API locally for higher file size limits or lower latency.

## Code Examples

### Minimal Initialization

The simplest way to initialize a Telego bot requires only the token:

```go
package main

import (
    "log"
    "github.com/mymmrac/telego"
)

func main() {
    bot, err := telego.NewBot("123456789:ABCdefGhIJKlmNoPQRstuVWXyz1234567")
    if err != nil {
        log.Fatal(err)
    }
    
    // Bot is ready to use
    _ = bot
}

```

### With Debug Logging

Following the pattern from [`examples/basic/main.go`](https://github.com/mymmrac/telego/blob/main/examples/basic/main.go), you should enable debug logging during development:

```go
package main

import (
    "log"
    "os"
    "github.com/mymmrac/telego"
)

func main() {
    bot, err := telego.NewBot(
        os.Getenv("TOKEN"),
        telego.WithDefaultDebugLogger(),
    )
    if err != nil {
        log.Fatal(err)
    }
    
    // Use the bot...
    _ = bot
}

```

### With Custom HTTP Client and API Server

For production environments requiring specific timeouts or proxy configurations:

```go
package main

import (
    "net/http"
    "time"
    "github.com/mymmrac/telego"
)

func main() {
    customHTTP := &http.Client{
        Timeout: 10 * time.Second,
    }
    
    bot, err := telego.NewBot(
        "123456789:ABCdefGhIJKlmNoPQRstuVWXyz1234567",
        telego.WithHTTPClient(customHTTP),
        telego.WithAPIServer("https://my-proxy.example.com"),
    )
    if err != nil {
        panic(err)
    }
    
    _ = bot
}

```

### Verifying the Connection

After initialization, verify the bot is properly configured by calling the `GetMe` method:

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "github.com/mymmrac/telego"
)

func main() {
    bot, err := telego.NewBot(os.Getenv("TOKEN"), telego.WithDefaultDebugLogger())
    if err != nil {
        log.Fatal(err)
    }
    
    me, err := bot.GetMe(context.Background())
    if err != nil {
        log.Fatal("Failed to get bot info:", err)
    }
    
    fmt.Printf("Bot initialized successfully: @%s (ID: %d)\n", me.Username, me.ID)
}

```

## Summary

- **Use `telego.NewBot()`** to initialize a Telego bot with a token, located in [`main/bot.go`](https://github.com/mymmrac/telego/blob/main/main/bot.go).
- **Token validation** occurs automatically using the regex `^\d+:[\w-]{35}$` to ensure Telegram compatibility.
- **Default components** include `FastHTTPCaller`, a token-masking logger, and the standard Telegram API server URL.
- **Functional options** defined in [`bot_options.go`](https://github.com/mymmrac/telego/blob/main/bot_options.go) allow customization of loggers, HTTP clients, and API endpoints without breaking the API.
- **Always handle errors** returned by `NewBot()` to catch invalid tokens or configuration issues before runtime.

## Frequently Asked Questions

### What happens if I pass an invalid token to NewBot?

`NewBot` returns an error immediately without allocating the bot instance. The internal `validateToken` function checks that your token matches the required format `^\d+:[\w-]{35}$` (digits, colon, 35 alphanumeric characters). If your token is empty, malformed, or contains invalid characters, the function returns an error before any network components are initialized.

### Can I change the HTTP client after initializing the bot?

No, the HTTP client must be configured during initialization using the `WithHTTPClient()` or `WithAPICaller()` options in [`bot_options.go`](https://github.com/mymmrac/telego/blob/main/bot_options.go). The `Bot` struct stores the caller implementation as a private field set during construction. If you need different timeout settings or transport configurations, you must create a new bot instance with the updated client options.

### How do I enable debug logging to see API requests?

Pass `telego.WithDefaultDebugLogger()` as an option to `NewBot()`. This replaces the default logger (which masks the token for security) with a debug implementation that prints detailed request and response information, including HTTP methods, URLs, and payload data. This option is defined in [`bot_options.go`](https://github.com/mymmrac/telego/blob/main/bot_options.go) and is recommended for development environments only.

### Is it possible to use a local Telegram Bot API server instead of the cloud?

Yes, use the `WithAPIServer(url)` option when calling `NewBot()`. This option overrides the default `https://api.telegram.org` endpoint with your custom URL, such as `http://localhost:8081` for a local Bot API server instance. This is useful for handling larger file uploads or reducing latency when running the bot infrastructure geographically close to the API server.