# How to Change Telego API Server for Testing: Complete Configuration Guide

> Easily change the Telego API server for testing. Configure your bot with WithAPIServer and WithTestServerPath for the official Telegram sandbox environment. Read our guide now.

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

---

**Use the `WithAPIServer` BotOption to override the default `https://api.telegram.org` endpoint, or combine it with `WithTestServerPath()` to enable Telegram's official sandbox environment.**

When building test suites or integrating with local Bot API servers, you need to change Telego's API server configuration. The `mymmrac/telego` library provides flexible options to redirect all API calls to custom endpoints without modifying your application logic.

## Understanding Telego's API Server Architecture

Telego constructs every Bot API request from the **`apiURL`** field in the `Bot` struct. By default, this field initializes from the constant defined in [`bot.go`](https://github.com/mymmrac/telego/blob/main/bot.go):

```go
const defaultBotAPIServer = "https://api.telegram.org"

```

([bot.go:23-24](https://github.com/mymmrac/telego/blob/main/bot.go#L23-L24))

All higher-level methods—`GetMe`, `SendMessage`, `GetUpdates`—automatically build request URLs using this base address combined with your bot token and the specific API method path.

## Methods to Change the Telego API Server

### Using WithAPIServer for Custom Endpoints

The **`WithAPIServer`** BotOption validates your custom URL and assigns it to `bot.apiURL` during initialization. This option lives in [`bot_options.go`](https://github.com/mymmrac/telego/blob/main/bot_options.go) and performs validation to ensure the server string is non-empty:

```go
func WithAPIServer(apiURL string) BotOption {
    return func(bot *Bot) error {
        if apiURL == "" {
            return errors.New("empty bot api server url")
        }
        bot.apiURL = apiURL
        return nil
    }
}

```

([bot_options.go:10-20](https://github.com/mymmrac/telego/blob/main/bot_options.go#L10-L20))

### Enabling Telegram's Test Sandbox with WithTestServerPath

When testing against Telegram's official sandbox environment, you need the **`WithTestServerPath`** option. This toggles `bot.useTestServerPath` to `true`, which prefixes all request paths with `/test/`:

```go
func WithTestServerPath() BotOption {
    return func(bot *Bot) error {
        bot.useTestServerPath = true
        return nil
    }
}

```

([bot_options.go:22-30](https://github.com/mymmrac/telego/blob/main/bot_options.go#L22-L30))

The resulting URL pattern becomes `https://<api-server>/bot<token>/test/<method>` instead of the standard `/bot<token>/<method>` path.

### Combining Both Options

These options are fully composable. You can point Telego at a local mock server while enabling the test path flag, or use the official Telegram test server with a custom API URL:

```go
// Custom host + test path
bot, err := telego.NewBot(token,
    telego.WithAPIServer("http://localhost:8080"),
    telego.WithTestServerPath(),
)

```

## Practical Code Examples

### Example 1: Local Mock Server for Integration Testing

Point Telego to a local HTTP server to capture and mock API responses without hitting Telegram's live infrastructure:

```go
package main

import (
    "context"
    "log"
    "os"

    "github.com/mymmrac/telego"
)

func main() {
    token := os.Getenv("TOKEN")
    bot, err := telego.NewBot(token,
        telego.WithAPIServer("http://localhost:8080"), // ← custom API server
    )
    if err != nil {
        log.Fatalf("Bot init error: %v", err)
    }

    // This request hits http://localhost:8080/bot<token>/getMe
    me, err := bot.GetMe(context.Background())
    if err != nil {
        log.Fatalf("GetMe error: %v", err)
    }
    log.Printf("Bot user: %+v\n", me)
}

```

### Example 2: Telegram's Official Test Sandbox

Enable the test server path to use Telegram's sandbox environment, which isolates your bot from production data:

```go
package main

import (
    "context"
    "log"
    "os"

    "github.com/mymmrac/telego"
)

func main() {
    token := os.Getenv("TOKEN")
    bot, err := telego.NewBot(token,
        telego.WithAPIServer("https://api.telegram.org"), // default, explicit for clarity
        telego.WithTestServerPath(),                     // ← enable /test/ prefix
    )
    if err != nil {
        log.Fatalf("Bot init error: %v", err)
    }

    // This call hits https://api.telegram.org/bot<token>/test/getMe
    me, err := bot.GetMe(context.Background())
    if err != nil {
        log.Fatalf("GetMe error: %v", err)
    }
    log.Printf("Bot user (test server): %+v\n", me)
}

```

### Example 3: Repository Configuration Example

The official [`examples/configuration/main.go`](https://github.com/mymmrac/telego/blob/main/examples/configuration/main.go) file demonstrates combining both options:

```go
bot, err := telego.NewBot(botToken,
    telego.WithAPIServer("new bot api server"), // replace with your test URL
    telego.WithTestServerPath(),                // optional test-path flag
    // …additional options…
)

```

([examples/configuration/main.go:22-27](https://github.com/mymmrac/telego/blob/main/examples/configuration/main.go#L22-L27))

## How Request URLs Are Constructed

Understanding the URL construction helps debug configuration issues. Telego builds final request URLs by combining three components:

1. **Base URL** (`bot.apiURL`): Set via `WithAPIServer`, defaults to `https://api.telegram.org`
2. **Path prefix**: `/bot<token>` always present
3. **Test flag** (`bot.useTestServerPath`): When true, inserts `/test/` before the method name

The resulting pattern follows:

- **Production**: `https://api.telegram.org/bot<token>/getMe`
- **Test sandbox**: `https://api.telegram.org/bot<token>/test/getMe`
- **Custom server**: `http://localhost:8080/bot<token>/getMe`

This architecture ensures that once you configure the API server during `NewBot()`, all subsequent API calls automatically use your specified endpoint without requiring per-method changes.

## Summary

- **Default behavior**: Telego sends all requests to `https://api.telegram.org` as defined in [`bot.go`](https://github.com/mymmrac/telego/blob/main/bot.go).
- **Custom API server**: Use `WithAPIServer("http://your-server")` to redirect traffic to local mocks or alternative hosts.
- **Test sandbox**: Enable `WithTestServerPath()` to prefix requests with `/test/`, routing to Telegram's official test environment.
- **Zero code changes**: After configuration in `NewBot()`, all methods like `GetMe` and `SendMessage` automatically use the new endpoint.
- **Validation**: `WithAPIServer` rejects empty strings to prevent configuration errors.

## Frequently Asked Questions

### How do I point Telego to a local Bot API server for development?

Use the `WithAPIServer` option when creating your bot instance. Pass the local server URL (e.g., `http://localhost:8081`) as the argument. This overrides the default `https://api.telegram.org` endpoint and directs all requests to your local installation, which is useful for testing large file uploads or avoiding rate limits during development.

### What is the difference between WithAPIServer and WithTestServerPath in Telego?

`WithAPIServer` changes the **base URL** of the API endpoint (the hostname and protocol), while `WithTestServerPath` modifies the **request path** by inserting `/test/` before the method name. You use `WithAPIServer` to point to local mocks or custom servers, and `WithTestServerPath` to access Telegram's official test sandbox regardless of which host you're targeting.

### Can I use both custom API server and test server path together?

Yes, these options are fully composable and independent. You can combine `WithAPIServer("http://localhost:8080")` with `WithTestServerPath()` to send requests to `http://localhost:8080/bot<token>/test/<method>`. This is particularly useful for integration testing where you want to validate that your local mock server correctly handles the `/test/` path prefix that Telegram's real test environment uses.

### Where does Telego store the API server configuration?

Telego stores the API server URL in the **`apiURL`** field of the `Bot` struct, defined in [`bot.go`](https://github.com/mymmrac/telego/blob/main/bot.go). The `WithAPIServer` option writes to this field during bot initialization, and all subsequent HTTP requests use this value as the base URL. The field is unexported (lowercase), meaning it can only be modified through the official `BotOption` functions, ensuring configuration integrity.