Client Config

Overview

The ClientConfig struct provides extensive configuration options to customize your Gogram client behavior, from basic authentication to advanced networking settings.

Basic Configuration

client, err := telegram.NewClient(telegram.ClientConfig{
    AppID:   6,
    AppHash: "your_app_hash", // Optional, but required for authentication
})

While AppHash is optional in the config, it’s required for authentication and certain API methods. You can omit it only if you’re importing an existing session.

Configuration Fields

Required Fields

AppID

int32

required

The App ID from my.telegram.org. Required for all clients.

AppHash

string

The App Hash from my.telegram.org. Optional in config, but required for:

Authentication (Login/LoginBot)
Certain API methods that need app credentials
Initial client setup without existing session

Can be omitted if you’re importing an already authenticated session.

Session Management

Session

string

default:"session.dat"

The session file path to use for storing authentication data.

Session: "./sessions/my_bot.dat"

StringSession

string

Use a string session instead of a file. Useful for cloud deployments.

StringSession: "1BVtsOIABu7V1..."

SessionName

string

Custom name for the session. Alternative to Session field.

SessionName: "my_bot_session"

SessionAESKey

string

AES encryption key for the session file (32 characters). Optional, not needed unless you need extra protection from string session being leaked.

SessionAESKey: "12345678901234567890123456789012"

MemorySession

bool

default:"false"

Don’t save the session to a file. Session is lost when the program exits.

MemorySession: true

Device Configuration

DeviceConfig

Device information sent to Telegram servers.

DeviceConfig: telegram.DeviceConfig{
    DeviceModel:    "IPhone",
    SystemVersion:  "17.0",
    AppVersion:     "1.0.0",
    LangCode:       "en",
    SystemLangCode: "en-US",
}

Network Configuration

DataCenter

int

default:"4"

The data center to connect to (1-5). Default is DC 4.

DataCenter: 2

IpAddr

string

Manually specify the IP address of the DC to connect to.

IpAddr: "149.154.167.50:443"

LocalAddr

string

Local address binding for multi-interface support (IP:port).

LocalAddr: "192.168.1.100:0"

ForceIPv6

bool

default:"false"

Force the client to use IPv6 connections.

ForceIPv6: true

Proxy

Proxy configuration for routing traffic. See Proxy Configuration.

Proxy: telegram.ProxyFromURL("socks5://username@password:ip@port")

UseWebSocket

bool

default:"false"

Use WebSocket transport instead of TCP. This must be enabled to use the library inside browsers, since they don’t allow TCP connections from JavaScript.

UseWebSocket: true

UseWebSocketTLS

bool

default:"false"

Use wss:// (WebSocket over TLS) instead of ws://.

UseWebSocketTLS: true

Transport & Protocol

TransportMode

string

default:"Abridged"

The transport mode to use. Options: Abridged, Intermediate, PaddedIntermediate, Full.

TransportMode: "Abridged" // default

PublicKeys

[]*rsa.PublicKey

Custom public keys to verify the server with.

PublicKeys: []*rsa.PublicKey{customKey}

TestMode

bool

default:"false"

Use the test data centers instead of production.

TestMode: true

Behavior & Features

ParseMode

string

default:"HTML"

Default parse mode for messages. Options: HTML, Markdown.

ParseMode: "Markdown"

NoUpdates

bool

default:"false"

Don’t handle updates. Useful for stateless bots.

NoUpdates: true

DisableCache

bool

default:"false"

Disable caching peer and chat information.

DisableCache: true

CacheSenders

bool

default:"false"

Cache the exported file operation senders.

CacheSenders: true

Cache

*CACHE

Custom cache implementation for storing peer information. See Client Cache.

Cache: customCache

NoPreconnect

bool

default:"false"

Don’t preconnect to the DC until Connect() is called. Otherwise it preconnects if string session is provided.

NoPreconnect: true

Commands & Messages

CommandPrefixes

string

default:"/!"

Command prefixes to recognize. Can be multiple characters.

CommandPrefixes: ".?!-/"

AlbumWaitTime

int64

default:"500"

Time to wait for album messages in milliseconds.

AlbumWaitTime: 1000 // 1 second

Rate Limiting & Timeouts

SleepThresholdMs

int

default:"10000"

Threshold in milliseconds to sleep before flood wait.

SleepThresholdMs: 5000

Timeout

int

default:"60"

TCP connection timeout in seconds.

Timeout: 30

ReqTimeout

int

default:"60"

RPC request timeout in seconds.

ReqTimeout: 120

FloodHandler

func(err error) bool

Custom handler for flood wait errors. Return true to retry, false to drop the request

FloodHandler: func(err error) bool {
    log.Printf("Flood wait: %v", err)
    return true // Retry after waiting
}

Logging

LogLevel

default:"InfoLevel"

The library log level. Options: DebugLevel, InfoLevel, WarnLevel, ErrorLevel.

LogLevel: telegram.DebugLevel

Logger

Custom logger implementation. See Logging.

Logger: customLogger

ErrorHandler

func(err error)

Custom error handler for global error handling.

ErrorHandler: func(err error) {
    log.Printf("Error: %v", err)
}

Using ClientConfigBuilder

For more convenient configuration, use the ClientConfigBuilder:

config := telegram.NewClientConfigBuilder(6, "your_app_hash").
    WithDeviceConfig("IPhone", "17.0", "1.0.0", "en", "en-US", "ios").
    WithSession("my_session.dat").
    WithParseMode("Markdown").
    WithDataCenter(2).
    WithProxy("socks5://localhost:1080").
    WithLogLevel(telegram.DebugLevel).
    Build()

client, err := telegram.NewClient(config)

Builder Methods

WithDeviceConfig(deviceModel, systemVersion, appVersion, langCode, sysLangCode, langPack string)

Complete Example

package main

import (
    "log"
    "github.com/amarnathcjd/gogram/telegram"
)

func main() {
    // Using builder pattern
    config := telegram.NewClientConfigBuilder(6, "your_app_hash").
        WithDeviceConfig("Server", "1.0", "1.0.0", "en", "en-US", "").
        WithSession("session.dat").
        WithParseMode("HTML").
        WithLogLevel(telegram.InfoLevel).
        Build()
    
    client, err := telegram.NewClient(config)
    if err != nil {
        log.Fatal(err)
    }
    
    client.Conn()
    client.LoginBot("BOT_TOKEN")
    
    log.Println("Bot started successfully!")
    client.Idle()
}

Best Practices

Use Builder Pattern

Use ClientConfigBuilder for cleaner, more maintainable configuration.

Encrypt Sessions

Always use SessionAESKey to encrypt session files in production.

Set Timeouts

Configure appropriate timeouts based on your network conditions.

Handle Floods

Implement custom FloodHandler to manage rate limiting gracefully.

Use String Sessions

For cloud deployments, prefer StringSession over file-based sessions.

Enable Logging

Use appropriate LogLevel for debugging and production monitoring.

Next Steps

Authentication

Learn how to authenticate your client

Proxy Configuration

Configure proxy settings

Event Handlers

Handle messages and updates

Getting Started

Core Concepts

Handlers

Update Types

Help

Overview

Basic Configuration

Configuration Fields

Required Fields

Session Management

Device Configuration

Network Configuration

Transport & Protocol

Behavior & Features

Commands & Messages

Rate Limiting & Timeouts

Logging

Using ClientConfigBuilder

Builder Methods

Complete Example

Best Practices

Use Builder Pattern

Encrypt Sessions

Set Timeouts

Handle Floods

Use String Sessions

Enable Logging

Next Steps

Authentication

Proxy Configuration

Event Handlers

Getting Started

Core Concepts

Handlers

Update Types

Help

​Overview

​Basic Configuration

​Configuration Fields

​Required Fields

​Session Management

​Device Configuration

​Network Configuration

​Transport & Protocol

​Behavior & Features

​Commands & Messages

​Rate Limiting & Timeouts

​Logging

​Using ClientConfigBuilder

​Builder Methods

​Complete Example

​Best Practices

Use Builder Pattern

Encrypt Sessions

Set Timeouts

Handle Floods

Use String Sessions

Enable Logging

​Next Steps

Authentication

Proxy Configuration

Event Handlers

Overview

Basic Configuration

Configuration Fields

Required Fields

Session Management

Device Configuration

Network Configuration

Transport & Protocol

Behavior & Features

Commands & Messages

Rate Limiting & Timeouts

Logging

Using ClientConfigBuilder

Builder Methods

Complete Example

Best Practices

Next Steps