Table of Contents

tgapi Overview RU

Что такое tgapi
Два главных клиента
Когда использовать MessageContext, а когда tgapi
Typed methods first
APIOpts
API и Uploader
Close() важен
Downloads и низкоуровневые запасные пути
Что читать дальше

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

tgapi Overview RU

English version: tgapi-Overview

Это краткая русскоязычная версия страницы про tgapi. Полная и наиболее актуальная страница: tgapi-Overview.

Что такое `tgapi`

tgapi — это низкоуровневый слой Telegram Bot API под высокоуровневым механизмом выполнения Laniakea.

Используй его, когда нужен:

direct access к Telegram methods;
явный контроль над parameter structs;
uploads и downloads;
raw request building.

Два главных клиента

tgapi.API для JSON requests;
tgapi.Uploader для multipart uploads.

Это разделение специально сделано, чтобы JSON methods и file upload methods не смешивались в одну слишком размытую abstraction.

Когда использовать `MessageContext`, а когда `tgapi`

Используй MessageContext, когда:

ты уже внутри handler'а;
нужен обычный поток reply/edit/delete/callback.

Используй tgapi, когда:

у MessageContext нет нужного вспомогательного метода;
ты работаешь вне потока обработчика;
нужен более низкоуровневый контроль;
нужно работать с uploads/downloads напрямую.

Typed methods first

Обычный tgapi-подход — использовать typed methods и typed params.

api := tgapi.NewAPI(tgapi.NewAPIOpts(token))
defer api.Close()

msg, err := api.SendMessage(tgapi.SendMessage{
	ChatID: chatID,
	Text:   "Привет",
})

Это безопаснее и удобнее, чем вручную собирать raw requests.

`APIOpts`

Через NewAPIOpts(token) можно настраивать:

HTTP client;
test server;
custom API URL;
limiter;
режим сброса у limiter.

`API` и `Uploader`

API отвечает за:

JSON request encoding;
HTTP execution;
поведение retry и limiter;
response decoding.

Uploader отвечает за:

multipart file uploads;
методы, которым нужны binary bodies.

Например:

uploader := tgapi.NewUploader(api)
defer uploader.Close()

_, err := uploader.SendPhoto(tgapi.UploadPhoto{
	ChatID: chatID,
	Caption: "Кот",
}, tgapi.NewUploaderFile("cat.jpg", data))

`Close()` важен

У API и Uploader есть собственный жизненный цикл.

Если ты владеешь этими объектами напрямую, их надо закрывать явно.

Если ими владеет Bot, это делает bot.Close().

Downloads и низкоуровневые запасные пути

tgapi покрывает и поток загрузки файлов, и сырые конструкторы запросов.

Это полезно, когда типизированного вспомогательного метода еще нет или нужен очень точный контроль.

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

Wiki

tgapi Overview RU

Что такое `tgapi`

Два главных клиента

Когда использовать `MessageContext`, а когда `tgapi`

Typed methods first

`APIOpts`

`API` и `Uploader`

`Close()` важен

Downloads и низкоуровневые запасные пути

Что читать дальше

Navigation

Start here

Runtime and Architecture

Interaction and Telegram API

Practical Guides

Maintenance

Wiki

tgapi Overview RU

Что такое tgapi

Два главных клиента

Когда использовать MessageContext, а когда tgapi

Typed methods first

APIOpts

API и Uploader

Close() важен

Downloads и низкоуровневые запасные пути

Что читать дальше

Navigation

Start here

Runtime and Architecture

Interaction and Telegram API

Practical Guides

Maintenance

Что такое `tgapi`

Когда использовать `MessageContext`, а когда `tgapi`

`APIOpts`

`API` и `Uploader`

`Close()` важен