Your first bot

Before you start

You need three things to make it through this page: Go 1.21 or newer, a bot token from @BotFather, and an api id + hash pair from my.telegram.org. The Installation page walks through getting all three if you do not have them yet.

An echo bot in five steps

1.  

   Create a fresh Go module

   In an empty directory, initialise a module. The name is arbitrary — it does not have to be a real import path unless you plan to publish this bot.

   terminal

   $mkdir echo-bot && cd echo-bot

   $go mod init echo-bot

2.  

   Pull in the library

   One import path covers everything you need.

   terminal

   $go get github.com/amarnathcjd/gogram/telegram@latest

3.  

   Drop the program in main.go

   Twenty-five lines total. The first block builds the client, the second logs in as the bot, the third registers a handler that echoes any private-chat text back.

   package main
   
   import (
   	"log"
   	"os"
   
   	"github.com/amarnathcjd/gogram/telegram"
   )
   
   func main() {
   	client, err := telegram.NewClient(telegram.ClientConfig{
   		AppID:   12345,
   		AppHash: "abcdef0123456789abcdef0123456789",
   		Session: "echo-bot.session",
   	})
   	if err != nil {
   		log.Fatal(err)
   	}
   
   	if err := client.Connect(); err != nil {
   		log.Fatal(err)
   	}
   
   	if err := client.LoginBot(os.Getenv("BOT_TOKEN")); err != nil {
   		log.Fatal(err)
   	}
   
   	client.On("message:*", func(m *telegram.NewMessage) error {
   		if m.IsPrivate() && m.Text() != "" {
   			_, err := m.Reply(m.Text())
   			return err
   		}
   		return nil
   	})
   
   	log.Println("bot ready")
   	client.Idle()
   }

   package main
   
   import (
   	"log"
   	"os"
   
   	"github.com/amarnathcjd/gogram/telegram"
   )
   
   func main() {
   	client, err := telegram.NewClient(telegram.ClientConfig{
   		AppID:   12345,
   		AppHash: "abcdef0123456789abcdef0123456789",
   		Session: "echo-bot.session",
   	})
   	if err != nil {
   		log.Fatal(err)
   	}
   
   	if err := client.Connect(); err != nil {
   		log.Fatal(err)
   	}
   
   	if err := client.LoginBot(os.Getenv("BOT_TOKEN")); err != nil {
   		log.Fatal(err)
   	}
   
   	client.On("message:*", func(m *telegram.NewMessage) error {
   		if m.IsPrivate() && m.Text() != "" {
   			_, err := m.Reply(m.Text())
   			return err
   		}
   		return nil
   	})
   
   	log.Println("bot ready")
   	client.Idle()
   }

4.  

   Export the bot token and run it

   The token comes from BotFather. Keep it out of your source; an env var is the simplest option and survives moving the code around.

   terminal

   $export BOT_TOKEN=123456:your-bot-token-from-botfather

   $go run main.go

5.  

   Talk to your bot

   Open Telegram, find your bot by username, tap Start, and send anything. It should echo back within a few hundred milliseconds. The first run also writes echo-bot.session next to your binary — restarting the program reuses the session instead of logging in again.

Anatomy of the program

Four phases, one per top-level call:

1. Construct. NewClient validates the config and prepares an in-memory MTProto sender. No network yet. The Session path is where the auth key will be written after the first successful login.
2. Connect. Connect opens the TCP (or WebSocket) connection to a data centre, performs the obfuscation handshake, and either loads the existing auth key from the session file or runs a fresh Diffie-Hellman to make one.
3. Log in. LoginBot exchanges the bot token for an authenticated session with the current DC. If the bot lives on a different DC, the server tells the client to migrate; the client handles that transparently.
4. Listen. On registers an update handler. The message:* pattern matches every incoming message; the filter inside the handler restricts to private-chat text. client.Idle() blocks the main goroutine so the program does not exit — the dispatcher runs on its own worker pool.

What if it does not work

Fold-outs for the most common failure modes:

Next steps

Now that you have a running client, the sidebar is organised roughly in the order you will reach for things. A few tent-poles:

• ClientConfig reference — every option, what it does.
• Sending messages — text, media, albums, replies.
• Dispatcher & handlers — the full handler model.
• NewMessage — every method on the message wrapper.
• Buttons & keyboards — inline UI without leaving Go.