Sessions

What a session is

After a successful login, the client holds an auth key: a 256-byte secret shared with the DC, plus a few metadata fields (DC id, user id, server salt). That bundle is the session. Persist it and the next program run skips login entirely; lose it and you start from scratch.

The library can store the bundle four ways. They are interchangeable; you can export from one and load into another.

Session file

client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:   12345,
	AppHash: "...",
	Session: "bot.session",
})

client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:   12345,
	AppHash: "...",
	Session: "bot.session",
})

Default and simplest. A binary blob next to your binary. Read once at startup, written after a successful login and after key rotation. Use this for long-running services where you have a writable filesystem.

String session

The same data, base64-encoded. Useful when you do not have writable disk (serverless, ephemeral containers) or when you want to provision the session out-of-band.

s := client.ExportStringSession()
// stash this in env, vault, kubernetes secret, whatever
os.WriteFile("session.txt", []byte(s), 0600)

// later, on a different host:
client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:         12345,
	AppHash:       "...",
	StringSession: os.Getenv("TG_SESSION"),
})

s := client.ExportStringSession()
// stash this in env, vault, kubernetes secret, whatever
os.WriteFile("session.txt", []byte(s), 0600)

// later, on a different host:
client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:         12345,
	AppHash:       "...",
	StringSession: os.Getenv("TG_SESSION"),
})

The string is portable across hosts and across OSes. The library will accept the same string from a session file generated on Linux, used on Windows, used in WASM.

In-memory session

client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:         12345,
	AppHash:       "...",
	MemorySession: true,
})

client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:         12345,
	AppHash:       "...",
	MemorySession: true,
})

The auth key lives in memory and dies with the process. Good for tests, short-lived workers, and the WASM build of the Tools where there is no disk to write to and no secret to persist.

In-memory sessions still need a successful login on every startup. Combine with StringSession if you want to load a pre-existing session into memory without ever touching the file system:

telegram.ClientConfig{
	StringSession: os.Getenv("TG_SESSION"),
	MemorySession: true,
}

telegram.ClientConfig{
	StringSession: os.Getenv("TG_SESSION"),
	MemorySession: true,
}

Encrypted session file

For session files that live alongside other application files but should not be readable plaintext. Provide an AES-256 key — 32 raw bytes or 64 hex characters — in SessionAESKey:

client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:         12345,
	AppHash:       "...",
	Session:       "bot.session",
	SessionAESKey: os.Getenv("SESSION_KEY"),
})

client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:         12345,
	AppHash:       "...",
	Session:       "bot.session",
	SessionAESKey: os.Getenv("SESSION_KEY"),
})

The file gets encrypted with AES-256-CBC under that key. Lose the key, lose the session permanently.

Moving sessions between hosts

1. On the source host call client.ExportStringSession() after a successful login.
2. Ship the string to the target host through a channel you trust.
3. On the target host pass it as StringSession.

Both clients must use the same api id and api hash — the auth key is bound to the application identity. If they differ, the server returns AUTH_KEY_UNREGISTEREDon the first request.

Invalidating a session

To kill the current session from inside the program:

if err := client.LogOut(); err != nil {
	log.Println("logout failed:", err)
}

if err := client.LogOut(); err != nil {
	log.Println("logout failed:", err)
}

That calls auth.logOut, which removes the auth key on the server side. The local session file or string becomes useless. If you only want to stop using a session locally without affecting the server, just delete the file (or stop loading the string) — the server keeps the key alive for many months of inactivity before forgetting it.

To kill another session without ending the current one, call the raw account.resetAuthorization TL method with the hash of the session you want to drop. account.getAuthorizations returns the list of currently active sessions with their hashes so you know which one to target.