telegram-bot-api: установка и первый код

Токен из второго урока лежит в переменной окружения — время писать код. Минимум, который нужен: установленный Go с go.dev, терминал и пять минут; если Go ещё не ставили, в базовом курсе есть отдельный урок про установку под все три системы. Никаких особых требований к окружению: библиотека написана на чистом Go, без CGO, и собирается на Linux, macOS и Windows одинаково. К концу урока у вас будет программа, которая запускается, проверяет токен у Telegram и печатает username бота в лог. Это скелет, на который в четвёртом уроке ляжет цикл обновлений и эхо-ответ, поэтому важно не просто скопировать код, а понять каждую строку — дальше он будет повторяться во всех двадцати двух уроках. Соберём всё по шагам, а в конце разберём, как читать сырые ответы Telegram — навык, который пригодится при любой неполадке.

Установка tgbotapi: go mod init и go get#

Любой Go-проект начинается с модуля. Создайте папку и инициализируйте её: go mod init github.com/you/echo-bot — путь модуля условен, для локального проекта подойдёт любое уникальное имя, позже он станет префиксом ваших собственных пакетов. Затем установка tgbotapi: go get github.com/go-telegram-bot-api/telegram-bot-api/v5. Команда скачает библиотеку, добавит её в блок require в go.mod с текущей версией пятого поколения и запишет контрольные суммы в go.sum. Суффикс /v5 — часть пути модуля по правилам семантического версионирования Go: без него компилятор пакет не найдёт, и это не опечатка, а контракт. Внешних зависимостей у библиотеки ноль — только стандартная библиотека, поэтому граф зависимостей остаётся коротким, а сборка быстрой. Отдельно про состояние проекта: оригинальный репозиторий заморожен, автор ушёл, API закреплён на пятой версии и больше не развивается. Для обучения это скорее плюс: примеры из любых туториалов совместимы, а принципы переезжают на преемников без переписывания.

Три команды старта

mkdir echo-bot && cd echo-bot

go mod init github.com/you/echo-bot

go get github.com/go-telegram-bot-api/telegram-bot-api/v5

Первая команда создаёт папку проекта. Вторая превращает её в модуль: появляется go.mod с объявленным путём. Третья добавляет зависимость telegram-bot-api/v5 в require и фиксирует контрольные суммы в go.sum. После этого библиотека готова к импорту — никаких дополнительных настроек ей не нужно, ни конфигов, ни переменных сборки.

Первый код: NewBotAPI и bot.Self#

Создайте main.go. Импорт пакета пишут с алиасом tgbotapi: за ним стоит путь github.com/go-telegram-bot-api/telegram-bot-api/v5 — так делают во всех примерах документации, включая README библиотеки; алиас совпадает с внутренним именем пакета, но прописывается явно, чтобы путь с дефисами не смущал ни редакторы, ни людей. Главная строка урока — bot, err := tgbotapi.NewBotAPI(token). Конструктор не просто заполняет структуру: он сразу ходит в сеть с методом getMe, проверяя токен. На успех возвращает указатель *BotAPI, где поле Self — данные вашего бота: id, UserName, FirstName. На отказ — error с сообщением Unauthorized: ловится на старте, а не после первого сообщения пользователя. С этого момента переменная bot — ваш единственный паспорт в Bot API: через неё пойдут и отправка сообщений, и получение обновлений.

Программа проверки токена целиком

package main

import (
        "log"

        tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
)

func main() {
        bot, err := tgbotapi.NewBotAPI("ВАШ_ТОКЕН_ИЗ_УРОКА_2")
        if err != nil {
                log.Panic(err)
        }

        bot.Debug = true

        log.Printf("Авторизован под аккаунтом %s", bot.Self.UserName)
}

NewBotAPI получает токен и тут же проверяет его запросом getMe — битый токен роняет программу в первую же секунду. bot.Debug = true включает логирование каждого HTTP-запроса и ответа: в консоли видно URL метода и JSON. bot.Self.UserName печатает username с подчёркиванием на конце — совпадает с тем, что вы придумывали в BotFather. Программа завершится сразу после лога: цикла обновлений пока нет.

go run main.go — и в консоль падают строки. Сначала debug-блоки: отправленный запрос, заголовки, ответ с JSON. Потом лог Авторизован под аккаунтом @YourHelper_bot — здесь %s из log.Printf подставляет bot.Self.UserName, поэтому строка совпадёт с тем, что вы придумали в BotFather. Если токен неверный, программа упадёт с паникой panic: Unauthorized — и это хорошо: ошибка конфигурации должна валить процесс на старте, а не обнаруживаться через сутки тишины. Если вместо этого ругается сеть dial tcp, соединение с api.telegram.org не проходит — проверьте доступность сети и VPN, в некоторых регионах API без прокси недоступен. Ещё один частый гость — cannot find main module: вы забыли go mod init, и Go не знает, куда складывать зависимость. Все ошибки первого запуска собраны в таблице ниже: пробегитесь по ней до своего запуска, чтобы узнавать виновника в лицо.

Ошибки первого запуска и что они значат#

Что видите	Причина	Что делать
panic: Unauthorized	токен неверный, отозван или скопирован с пробелом	сверить с BotFather, проверить переменную окружения
cannot find main module	в папке нет go.mod	выполнить go mod init перед go get
no required module provides package	зависимость не установлена или импорт без /v5	go get с суффиксом /v5, сверить строку импорта
dial tcp: i/o timeout	нет доступа к api.telegram.org	сеть, VPN или прокси

Что коммитить: go.mod, go.sum и .gitignore#

Репозиторий под бот заводится в тот же вечер, и здесь подстерегает первая ошибка с последствиями: в .gitignore летит go.sum. Логика понятна — файл похож на кэш, он генерируется автоматически и постоянно растёт. На деле go.sum — это замок: контрольные суммы версий, по которым чужая машина и ваш будущий сервер собирают ровно то, что проверяли вы. Удалите его из репозитория — и деплой из двадцать четвёртого урока молча подтянет свежий релиз библиотеки, а с ним и незнакомые отличия в поведении. Правило простое: go.mod и go.sum коммитятся всегда. Вторая ловушка — старые туториалы, где go get ставит исполняемые файлы: начиная с Go 1.17 команда только правит зависимости модуля, а исполняемые файлы устанавливает go install. Если автор видео 2019 года набирает другую команду — это не ваша ошибка, эпоха сменилась.

Как читать Debug-лог: URL, ok и result#

Каждый запрос Bot API — это адрес вида api.telegram.org/bot<токен>/имяМетода: метод getMe, sendMessage, getUpdates — всё после слэша. Ответ всегда завёрнут в один и тот же конверт: поле ok с true или false и либо result с данными, либо error_code с description. Debug-режим показывает и запрос, и ответ целиком, поэтому за вечер чтения логов вы выучите сырой API лучше, чем за неделю документации. На что смотреть: error_code 401 — проблема с токеном, 404 — опечатка в имени метода или токене, 409 — конфликт получателей обновлений, из пятого урока; описание в description обычно честно называет причину словами. Этот конверт — язык, на котором Telegram разговаривает с любой библиотекой: telegram-bot-api лишь разворачивает его в структуры и ошибки Go, поэтому умение читать сырой ответ экономит часы отладки на любом языке.

Debug=true и токен в логах

В режиме Debug библиотека печатает полные запросы — включая URL, в котором сидит токен, и тексты сообщений пользователей. Для обучения это незаменимо, для продакшена — слив секрета в журналы, которые часто читает весь ops-персонал или техподдержка хостинга. Правило: Debug включается переменной окружения или флагом на время отладки и выключается в деплое; на постоянке логируйте свои события, а не трафик библиотеки.

Подключение Telegram Bot API к Go: что даёт библиотека#

telegram-bot-api — тонкая обёртка: она не решает за вас, а переводит. Первый слой — типы: структуры Update, Message, User, Chat и конфиги вроде MessageConfig и UpdateConfig повторяют объекты официальной документации один в один. Второй слой — конструкторы: tgbotapi.NewMessage(chatID, text) вместо ручного заполнения структур — меньше полей, меньше опечаток, читается как фраза. Третий слой — транспорт: bot.Send отправляет конфиг HTTPS-запросом и разворачивает ответ в Message, а bot.GetUpdatesChan прячет цикл опроса в горутину и отдаёт канал обновлений. Всё, что библиотека не оборачивает, уходит через bot.Request с голым APIResponse — запасной выход есть всегда. Практический вывод: документацию Bot API на core.telegram.org можно читать напрямую — каждому полю там соответствует поле структуры библиотеки. Подключение Telegram Bot API к Go, которое мы сделали сегодня, — это карта местности для всех следующих уроков: синтаксис getUpdates разберём в пятом, sendMessage — в шестом.

Спорное мнение: тонкая обёртка лучше фреймворка#

Мнение, к которому я пришёл после пары мёртвых проектов: для ботов лучше тонкая обёртка вроде tgbotapi, а не фреймворк с роутерами, контейнерами зависимостей и слоями. Фреймворки обещают структуру, но структура бота живёт в сценариях диалога с пользователем, а не в папках architecture, и оборачивать три функции в шесть абстракций — работа ради работы. Граница, при которой мнение перестаёт работать: команда от трёх-четырёх разработчиков или десяток ботов с общим кодом — там общий фреймворк окупается дисциплиной, потому что код пересекается между проектами. Проверка на глаз: если в вашем проекте больше кода про архитектуру, чем про ответы людям, обёртка потеряна. Пока идёт обучение, пишите на том, что видите в примерах документации, — собственные абстракции вырастут сами, как только появится второй настоящий бот.

Проверка: конструктор бота

Что делает tgbotapi.NewBotAPI сразу при вызове?

Проверка: алиас импорта

Зачем в импорте пишут алиас tgbotapi?

Что напечатает программа с битым токеном

Прочитайте код и выберите, что он выведет:

func main() {
        bot, err := tgbotapi.NewBotAPI("110201543:неверный_токен")
        if err != nil {
                log.Panic(err)
        }

        bot.Debug = true
        log.Printf("Авторизован под аккаунтом %s", bot.Self.UserName)
}

Три команды старта по памяти

Впишите подкоманды go для инициализации модуля и установки пакета, затем конструктор бота.

go mod github.com/you/echo-bot go github.com/go-telegram-bot-api/telegram-bot-api/v5 bot, err := tgbotapi.(token)

Соберите программу проверки токена

Расставьте строки минимальной программы: от объявления пакета до лога с username.

Строки

Ваша программа

Нажимайте на строки слева, чтобы собрать программу

Библиотека стоит, токен подтверждён логом с username — фундамент готов. Дальше самое интересное: в четвёртом уроке к этому скелету прицепится цикл обновлений и появится первый живой эхо-бот, а в пятом разберём, что именно происходит внутри GetUpdatesChan и почему Timeout = 60 — не декорация. Весь план курса — на странице курса. И повторение из второго урока: токен прямо в main.go из примера — временная уступка ради простоты отладки; до первого коммита переезжайте на переменную окружения, ошибка Unauthorized в git-истории никого красит. Если базовый синтаксис Go ещё дрожит под ногами, укрепите его по базовому курсу параллельно с этим — импорты, ошибки и указатели из него понадобятся уже завтра.

Карточки: установка и первый код

Термин

go.mod

нажмите, чтобы перевернуть

Определение

Файл модуля: путь модуля, версия Go и блок require с зависимостями. Создаётся go mod init, зависимости добавляет go get.

1 / 6

Песочница урока

Редактируйте код и запускайте его прямо здесь — интерпретатор работает в браузере, ничего устанавливать не нужно. За каждый запуск — +2 XP.

Вывод

Запустите код, чтобы увидеть вывод.

Коротко: что запомнить

Установка tgbotapi: go mod init, затем go get github.com/go-telegram-bot-api/telegram-bot-api/v5 — суффикс /v5 обязателен.
NewBotAPI на старте делает getMe: битый токен роняет программу с Unauthorized сразу, а не при первом сообщении.
bot.Self хранит данные бота из getMe: id, UserName, FirstName.
Debug=true печатает весь трафик вместе с токеном в URL — включать для отладки, выключать в проде.
Библиотека — тонкая обёртка: типы и конструкторы повторяют официальную документацию Bot API один в один.
Репозиторий заморожен на v5: API стабилен, примеры совместимы, принципы переезжают на преемников.

Домашнее задание

Соберите проект урока по шагам: папка, go mod init, go get с суффиксом /v5, main.go с NewBotAPI и Debug. Запустите с токеном из второго урока и убедитесь, что в логе ваш username. Затем сломайте намеренно: сотрите один символ секретной части токена и найдите в выводе panic: Unauthorized; уберите /v5 из импорта и прочитайте ошибку компилятора. Чинить чужие проекты проще, когда видел обе ошибки впервые у себя в терминале.

Вопросы и ответы по уроку

Библиотека заморожена — брать ли сразу преемника?

Для обучения v5 остаётся лучшим входом: простые структуры, море примеров, стабильный API. Преемники вроде go-telegram/bot активнее развиваются, но строятся на тех же понятиях Bot API — переезд после курса занимает вечер, а не неделю.

Как обновить библиотеку до свежей версии?

go get -u github.com/go-telegram-bot-api/telegram-bot-api/v5 подтянет последний релиз пятой ветки и обновит go.mod. Мажорные изменения по правилам Go живут в новом пути импорта, поэтому ваша сборка не сломается молча под вами. Перед обновлением в рабочем проекте прогоните тесты — замороженная библиотека редкий случай, когда обновление почти всегда безопасно.

Можно ли писать бота вообще без библиотеки?

Да: Bot API — обычный HTTPS и JSON, хватает net/http и encoding/json из стандартной библиотеки. Библиотека экономит рутину — типы, конструкторы, разбор ответов. Понимание сырья всё равно полезно, поэтому Debug-режим и сырые ответы мы разбираем уже здесь.

Термины урока

Ключевые понятия из этого урока — короткие определения в глоссарии. Наведите на термин, чтобы вспомнить, откройте карточку для подробностей и ссылки на практику.