Go 1.27+Bot API 10.3MIT Licensev0.1.2

TeleIQ

A Go library for the Telegram Bot API.

Every type and method of Bot API 10.3 as typed Go code, and a framework for bots that run for months: it receives updates by long polling or webhook, handles the updates of each chat in order, retries failed requests, and never writes the bot token to errors or logs.

go get github.com/DhurghamAhmed/teleiq@latest

GitHub Documentation Examples

185

Bot API methods

400

Bot API types

dependencies

packages

Why TeleIQ

Built for bots that stay up: the hard parts of talking to Telegram are done for you.

The whole Bot API

Every one of the 185 methods and 400 types of Bot API 10.3 is typed Go, generated from Telegram's official documentation and checked for updates every day.

Only the standard library

No third-party dependencies: nothing extra to download, audit or keep up to date.

Ordered, never lost

The updates of each chat are handled one at a time and in order, and an update is confirmed to Telegram only after it is handled.

Retries and rate limits

Failed requests are retried after network errors, server errors and flood control, and an optional rate limiter paces requests in all and per chat.

Errors by name

Check errors with errors.Is: ErrBotBlocked, ErrChatNotFound, ErrMessageNotModified, ErrNotEnoughRights and more.

The token stays secret

The bot token never appears in errors or logs, so they can be shared safely.

Your first bot

From nothing to a running bot in four steps.

Install

TeleIQ needs Go 1.27 or later.

go get github.com/DhurghamAhmed/teleiq@latest

2
Get a token
Talk to @BotFather on Telegram, send /newbot and copy the token it gives you.

Write the bot

A complete bot that greets /start and repeats every other message.

main.go

package main

import (
	"context"
	"log"
	"os"
	"os/signal"

	"github.com/DhurghamAhmed/teleiq"
	"github.com/DhurghamAhmed/teleiq/bot"
)

func main() {
	// ctx ends on Ctrl+C, which stops the bot.
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()

	client, err := teleiq.NewClient(os.Getenv("BOT_TOKEN"))
	if err != nil {
		log.Fatal(err)
	}
	b := bot.New(client) // b is the bot
	b.OnCommand("start", bot.ReplyWith("Hello! Send me a message and I will repeat it."))
	// c is the current message; c.Send replies in its chat.
	b.OnMessage(func(ctx context.Context, c *bot.Context) error {
		return c.Send(ctx, "You said: "+c.Text())
	})
	if err := b.Run(ctx); err != nil { // receives updates until ctx ends
		log.Fatal(err)
	}
}

4
Run it
Start the bot, then open it in Telegram and send /start.
```
export BOT_TOKEN='<token from @BotFather>'
go run .
```

The packages

Use the client alone, or the whole framework. Each package has one job.

teleiq

The client: a method for every Bot API method, with retries, rate limits and default options.

NewClientSendMessagePtrErrBotBlocked

bot

The framework: long polling or webhook, handlers, middleware and shortcuts for replying.

NewOnCommandContext.SendRecovery

filter

Which updates a handler gets: commands, texts, every kind of media, chats and users.

CommandPrivatePhotoAnd / Or / Not

models

Every Bot API type, plus helpers for chats, files and keyboards.

MessageIDFileFromPathNewInlineKeyboard

fsm

Conversations of several steps, with the state of each user kept for you.

NewConversationStepStateNewMemory

webapp

Checks that the data of a Mini App really comes from Telegram.

ValidateValidateSignatureInitData

teleiqtest

A fake Bot API server for tests: no Telegram, no token.

NewServerPushRequestsWaitHandled

Every function, type and error, with its documentation.All on pkg.go.dev

Examples

Short and real: every snippet comes from the library's README and examples.

Required parameters are plain fields; optional ones are pointers, set with teleiq.Ptr. Errors match by name.

methods.go

me, err := client.GetMe(ctx)
if err != nil {
	log.Fatal(err)
}
_, err = client.SendMessage(ctx, teleiq.SendMessageParams{
	ChatID:              models.ID(123456789), // or models.Username("@channel")
	Text:                "Hello from " + me.FirstName,
	DisableNotification: teleiq.Ptr(true),
})
switch {
case errors.Is(err, teleiq.ErrBotBlocked):
	// The user blocked the bot.
case errors.Is(err, teleiq.ErrTooManyRequests):
	// Flood control that the retries could not wait out.
}

15 complete programs, each with a test, are in the examples folder.

Follow TeleIQ

News, help and the docs, right inside Telegram.

Channel@teleiqgo

Every new release, with what changed.

Group@teleiqgroup

Questions, ideas and help from other developers.

Docs bot@TeleIqGoBot

Type @TeleIqGoBot and a name in any chat to search the docs, with an example for everything.

GitHubDhurghamAhmed/teleiq

The source, the examples and the issues. A star helps.