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

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:

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

(bot.go:23-24)

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 and performs validation to ensure the server string is non-empty:

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)

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/:

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

(bot_options.go:22-30)

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:

// 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:

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:

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 file demonstrates combining both options:

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)

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.
• 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. 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.

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