tgconv

README

session-converter

Telegram session string converter for Go — decode, encode, and convert between every major MTProto library format.

Supported formats

Format	String sessions	SQLite files
Telethon	✓	✓
Pyrogram	✓	✓
GramJS	✓
mtcute	✓
MTKruto	✓
gogram	✓
gotgproto (gotd/td)	✓

Install

go get github.com/mtgo-labs/session-converter

CLI:

go install github.com/mtgo-labs/session-converter/cmd/tgconv@latest

Quick start

Go API

import tgconv "github.com/mtgo-labs/session-converter"

// Auto-detect format and decode
session, format, err := tgconv.Decode(sessionString)

// Convert to another format
pyrogramString, err := tgconv.Convert(sessionString, tgconv.FormatPyrogram)

// Read a SQLite session file and export as a string
session, _, err := tgconv.ReadSQLite("session.session")
str, _ := tgconv.Encode(session, tgconv.FormatTelethon)

CLI

# Convert (auto-detects source format)
tgconv convert "1ApWapzMBuwAAB..." -t pyrogram --api-id 2040 --user-id 123456789 --is-bot

# Show session info
tgconv info "AgAAB_gA-reNm..."

# Export from SQLite file
tgconv from-file session.session -t telethon

# List supported formats
tgconv list

Format reference

Format	Field	Encoding
Telethon	dc, ip, port, auth_key	"1" + base64url
Pyrogram	dc, api_id, test_mode, auth_key, user_id, is_bot	base64url (no prefix)
GramJS	dc, addr_len, addr, port, auth_key	"1" + base64std
mtcute	version, flags, dc_option (TL), user_id, is_bot, auth_key	base64url
MTKruto	dc_string, auth_key, api_id, is_bot, user_id	RLE + base64url
gogram	auth_key, hash, dc_id, ip_addr, app_id	"1BvE" + base64url(JSON)
gotgproto	dc, addr, auth_key, auth_key_id, salt, config	base64std(JSON)

License

Apache License 2.0

Documentation

Overview

Package tgconv converts Telegram session strings between library formats.

A session string encapsulates the data needed to connect to Telegram without re-authenticating: the data center ID, server address, port, and the 256-byte authorization key (plus optional fields like user ID and API ID).

Supported formats:

• Telethon
• Pyrogram
• GramJS
• mtcute
• MTKruto
• gogram
• gotgproto (gotd/td)

SQLite session files from Telethon and Pyrogram are also supported via ReadSQLite.

Index

• Variables
• func Convert(str string, to Format) (string, error)
• func ConvertFrom(str string, from, to Format) (string, error)
• func Decode(str string) (*Session, Format, error)
• func Encode(s *Session, format Format) (string, error)
• func EncodeGogram(s *Session) (string, error)
• func EncodeGotgproto(s *Session) (string, error)
• func EncodeGramJS(s *Session) (string, error)
• func EncodeMTKruto(s *Session) (string, error)
• func EncodeMtcute(s *Session) (string, error)
• func EncodePyrogram(s *Session) (string, error)
• func EncodeTelethon(s *Session) (string, error)
• type Format
  • func DetectFormat(str string) Format
• type Session
  • func DecodeFormat(str string, format Format) (*Session, error)
  • func DecodeGogram(str string) (*Session, error)
  • func DecodeGotgproto(str string) (*Session, error)
  • func DecodeGramJS(str string) (*Session, error)
  • func DecodeMTKruto(str string) (*Session, error)
  • func DecodeMtcute(str string) (*Session, error)
  • func DecodePyrogram(str string) (*Session, error)
  • func DecodeTelethon(str string) (*Session, error)
  • func (s *Session) FillDefaults()

Variables

var AllFormats = []Format{
	FormatTelethon,
	FormatPyrogram,
	FormatGramJS,
	FormatMtcute,
	FormatMTKruto,
	FormatGogram,
	FormatGotgproto,
}

AllFormats lists every supported format.

Functions

func Convert

func Convert(str string, to Format) (string, error)

Convert decodes a session from any format and re-encodes it to the target.

func ConvertFrom

func ConvertFrom(str string, from, to Format) (string, error)

ConvertFrom decodes from a known format and re-encodes.

func Decode

func Decode(str string) (*Session, Format, error)

Decode auto-detects the session string format and decodes it.

func Encode

func Encode(s *Session, format Format) (string, error)

Encode encodes a session into the specified format.

func EncodeGogram

func EncodeGogram(s *Session) (string, error)

EncodeGogram encodes a session in gogram string format.

Modern: "1BvE" + base64RawURL(json({key, hash, dc_id, ip_addr, app_id}))

func EncodeGotgproto

func EncodeGotgproto(s *Session) (string, error)

EncodeGotgproto encodes a session in gotgproto string format.

The format is base64std(json(gotgprotoSession)), where gotgprotoSession wraps gotd's session data:

{
  "Version": 1,
  "Data": base64(json({Version: 1, Data: {DC, Addr, AuthKey, AuthKeyID, Salt, Config}}))
}

func EncodeGramJS

func EncodeGramJS(s *Session) (string, error)

EncodeGramJS encodes a session in GramJS string format.

"1" + base64std(dc[1] + addr_len[2 BE] + addr_bytes[variable] + port[2 BE] + authkey[256])

func EncodeMTKruto

func EncodeMTKruto(s *Session) (string, error)

EncodeMTKruto encodes a session in MTKruto string format.

base64url(rleEncode(TL_string(dc) + TL_bytes(authkey) + int32(apiId) LE + byte(isBot) + int64(userId) LE))

The dc string is formatted as "<dcID>" or "<dcID>-test" for test mode.

func EncodeMtcute

func EncodeMtcute(s *Session) (string, error)

EncodeMtcute encodes a session in mtcute string format.

base64url(version[1]=3 + flags[4 LE] + dc_option(TL) + [media_dc(TL)] + user_id[8 LE] + is_bot(TL bool) + authkey(TL bytes))

func EncodePyrogram

func EncodePyrogram(s *Session) (string, error)

EncodePyrogram encodes a session in Pyrogram string format.

base64url(dc[1] + api_id[4 BE] + test_mode[1] + authkey[256] + user_id[8 BE] + is_bot[1]) No version prefix. Total payload: 271 bytes.

func EncodeTelethon

func EncodeTelethon(s *Session) (string, error)

EncodeTelethon encodes a session in Telethon string format.

Telethon's StringSession has a single version (prefix "1") and stores only what's needed to connect — it never serializes api_id:

"1" + base64url(dc[1] + ip[4|16] + port[2 BE] + authkey[256])

Mirrors Telethon v1 sessions/string.py (struct ">B{}sH256s", CURRENT_VERSION = "1"). AppID is dropped from the wire format on purpose.

Types

type Format

type Format string

Format identifies a session string encoding format.

const (
	FormatTelethon  Format = "telethon"
	FormatPyrogram  Format = "pyrogram"
	FormatGramJS    Format = "gramjs"
	FormatMtcute    Format = "mtcute"
	FormatMTKruto   Format = "mtkruto"
	FormatGogram    Format = "gogram"
	FormatGotgproto Format = "gotgproto"
)

func DetectFormat

func DetectFormat(str string) Format

DetectFormat attempts to identify the format without fully decoding.

type Session

type Session struct {
	DCID          int    // data center ID (1-5)
	ServerAddress string // IP address or hostname
	Port          int    // server port
	AuthKey       []byte // 256-byte MTProto authorization key
	AppID         int32  // API ID from my.telegram.org
	TestMode      bool   // connected to test servers
	UserID        int64  // authenticated user/bot ID
	IsBot         bool   // whether the account is a bot
}

Session holds the common fields extracted from any session format. Not every field is populated by every format — the auth key and DC ID are always present; the rest depend on the source.

func DecodeFormat

func DecodeFormat(str string, format Format) (*Session, error)

DecodeFormat decodes a session string in the specified format.

func DecodeGogram

func DecodeGogram(str string) (*Session, error)

DecodeGogram decodes a gogram session string (modern and legacy).

func DecodeGotgproto

func DecodeGotgproto(str string) (*Session, error)

DecodeGotgproto decodes a gotgproto session string.

Handles both the current format (Version + Data wrapping gotd JSON) and older formats where the JSON directly contains DCID, AuthKey, etc.

func DecodeGramJS

func DecodeGramJS(str string) (*Session, error)

DecodeGramJS decodes a GramJS session string.

func DecodeMTKruto

func DecodeMTKruto(str string) (*Session, error)

DecodeMTKruto decodes an MTKruto session string.

func DecodeMtcute

func DecodeMtcute(str string) (*Session, error)

DecodeMtcute decodes an mtcute session string.

func DecodePyrogram

func DecodePyrogram(str string) (*Session, error)

DecodePyrogram decodes a Pyrogram session string.

Format: base64url(dc[1] + api_id[4 BE] + test_mode[1] + authkey[256] + user_id[8 BE] + is_bot[1]) Total payload: 271 bytes. No version prefix, no legacy variants.

func DecodeTelethon

func DecodeTelethon(str string) (*Session, error)

DecodeTelethon decodes a Telethon session string. Telethon has a single version (prefix "1"), storing dc + ip + port + auth_key. No api_id.

func (*Session) FillDefaults

func (s *Session) FillDefaults()

FillDefaults populates ServerAddress and Port from DC defaults if they are zero. This is called after decoding formats that omit these fields, and should be called after constructing a Session manually (e.g., from SQLite).