---
title: "telegram-bot-api: установка и первый код"
description: "Установка tgbotapi за две команды: go mod init и go get, импорт tgbotapi, NewBotAPI с проверкой токена, Debug-режим — подключение Telegram Bot API к Go."
course: "Telegram-боты на Go: от эха до полноценного сервиса"
url: "https://golangmaster.ru/courses/telegram-bot/lessons/03-ustanovka-telegram-bot-api/"
published: "2026-09-19"
updated: "2026-09-25"
minutes: 18
---

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

*Курс «Telegram-боты на Go: от эха до полноценного сервиса», урок 3 из 25. ~18 минут. Обновлено 25.09.2026. Источник: https://golangmaster.ru/courses/telegram-bot/lessons/03-ustanovka-telegram-bot-api/*

Установка tgbotapi сводится к двум командам: go mod init в новой папке и go get пакета. В этом уроке выполним подключение Telegram Bot API к Go: первый код с NewBotAPI, debug-режим и проверка токена через bot.Self.

Токен из второго урока лежит в переменной окружения — время писать код. Минимум, который нужен: установленный Go с go.dev, терминал и пять минут; если Go ещё не ставили, в [базовом курсе](/courses/go-basics/) есть отдельный урок про установку под все три системы. Никаких особых требований к окружению: библиотека написана на чистом 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 закреплён на пятой версии и больше не развивается. Для обучения это скорее плюс: примеры из любых туториалов совместимы, а принципы переезжают на преемников без переписывания.

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

```go
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: через неё пойдут и отправка сообщений, и получение обновлений.

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

```go
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 сразу при вызове?

- Только создаёт структуру без обращений к сети
- ✅ Делает запрос getMe и проверяет токен
- Начинает получать обновления
- Отправляет приветствие пользователю

Конструктор ходит в сеть с getMe: живой токен даёт заполненное bot.Self, битый — ошибку Unauthorized. Поэтому неверный токен роняет программу на старте, а не при первом сообщении пользователя. Тот же приём используют для проверки токена из скриптов: NewBotAPI и выход.

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

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

- Без него код не скомпилируется
- Алиас обязан совпадать с версией пакета
- ✅ Это общепринятое соглашение: короткое имя для длинного пути с дефисами
- Алиас включает debug-режим

Пакет импортируется и без алиаса, но вся документация и примеры пишут tgbotapi явно: путь с дефисами неудобен, а короткое имя делает код предсказуемым для читателя. Алиас — локальное имя внутри файла: в разных файлах проекта он может быть разным, хотя так делать не стоит.

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

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

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

**Что выведет программа?**

- Авторизован под аккаунтом @GoMaster_bot
- ✅ panic: Unauthorized
- Ничего: программа молча завершится
- Справку по использованию библиотеки

getMe на неверный токен отвечает ошибкой, срабатывает ветка err != nil, и log.Panic печатает сообщение вместе со стеком и завершает процесс. Строка с bot.Self.UserName не выполнится никогда: переменная bot не заполнена, а паника уже прервала main. Именно поэтому Unauthorized от NewBotAPI — самая безобидная ошибка курса: она всегда в первую секунду.

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

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

```go
go mod ___ github.com/you/echo-bot

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

bot, err := tgbotapi.___(token)
```

Подсказка: Модуль создаёт go mod init, зависимость ставит go get, клиента бота возвращает NewBotAPI.

Правильные ответы в пропусках: `init`, `get`, `NewBotAPI`

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

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

Правильный порядок строк:

1. `package main`
2. `func main() {`
3. `bot, err := tgbotapi.NewBotAPI(token)`
4. `if err != nil { log.Panic(err) }`
5. `log.Printf("авторизован %s", bot.Self.UserName)`
6. `}`

Библиотека стоит, токен подтверждён логом с username — фундамент готов. Дальше самое интересное: в [четвёртом уроке](/courses/telegram-bot/lessons/04-pervyj-bot-echo/) к этому скелету прицепится цикл обновлений и появится первый живой эхо-бот, а в [пятом](/courses/telegram-bot/lessons/05-long-polling/) разберём, что именно происходит внутри GetUpdatesChan и почему Timeout = 60 — не декорация. Весь план курса — на [странице курса](/courses/telegram-bot/). И повторение из второго урока: токен прямо в main.go из примера — временная уступка ради простоты отладки; до первого коммита переезжайте на переменную окружения, ошибка Unauthorized в git-истории никого красит. Если базовый синтаксис Go ещё дрожит под ногами, укрепите его по [базовому курсу](/courses/go-basics/) параллельно с этим — импорты, ошибки и указатели из него понадобятся уже завтра.

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

- **go.mod** — Файл модуля: путь модуля, версия Go и блок require с зависимостями. Создаётся go mod init, зависимости добавляет go get.
- **tgbotapi** — Общепринятый алиас импорта пакета github.com/go-telegram-bot-api/telegram-bot-api/v5 — короткое имя для длинного пути.
- **NewBotAPI** — Конструктор *BotAPI: проверяет токен запросом getMe, при ошибке возвращает Unauthorized. Вызывается на старте каждой программы.
- **bot.Self** — Структура User с данными бота из getMe: id, UserName, FirstName. Заполняется уже в NewBotAPI.
- **bot.Debug** — Флаг логирования всего HTTP-трафика библиотеки: URL с токеном и тела запросов. Инструмент отладки, выключаемый в продакшене.
- **getMe** — Метод Bot API: по токену возвращает описание бота. Без кода проверяется открытием api.telegram.org/bot<токен>/getMe в браузере.

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

- Установка 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-режим и сырые ответы мы разбираем уже здесь.