A memory-safe, high-performance Telegram Bot API implementation in Zig
Build powerful bots with zero allocations in hot paths and compile-time guarantees
🤖 Complete Bot API Support
- 📨 Message Handling: Send, receive, edit, and delete messages
- 📁 File Operations: Upload and download files with streaming support
- 🎯 Inline Queries: Full inline mode support
- 🔗 Webhooks: Secure webhook management
- 🎮 Interactive Elements: Keyboards, buttons, and callbacks
- 📊 Rich Media: Photos, videos, documents, and more
- Zig 0.14.0+ (Download here)
- Telegram Bot Token (Get from @BotFather)
Option 1: Using Zig Package Manager (Recommended)
# Add to your build.zig.zon
zig fetch --save git+https://github.com/Nyarum/zigtgshka.git
Your build.zig.zon should look like:
.{
.name = "my_bot",
.version = "0.0.0",
.minimum_zig_version = "0.14.0",
.dependencies = .{
.zigtgshka = .{
.url = "git+https://github.com/Nyarum/zigtgshka.git",
.hash = "1220...", // This will be auto-generated by zig fetch
},
},
.paths = .{
"build.zig",
"build.zig.zon",
"src",
},
}
Complete build.zig example:
const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
// Add zigtgshka dependency
const telegram_dependency = b.dependency("zigtgshka", .{
.target = target,
.optimize = optimize,
});
// Create your executable
const exe = b.addExecutable(.{
.name = "my_bot",
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});
// Import the telegram module
exe.root_module.addImport("telegram", telegram_dependency.module("telegram"));
exe.linkLibC(); // Required for HTTP client
b.installArtifact(exe);
// Run step
const run_cmd = b.addRunArtifact(exe);
run_cmd.step.dependOn(b.getInstallStep());
if (b.args) |args| {
run_cmd.addArgs(args);
}
const run_step = b.step("run", "Run the app");
run_step.dependOn(&run_cmd.step);
}
Option 2: Git Submodule
git submodule add https://github.com/Nyarum/zigtgshka.git libs/telegram
const telegram_mod = b.addModule("telegram", .{
.root_source_file = b.path("libs/telegram/src/telegram.zig"),
.target = target,
.optimize = optimize,
});
exe.root_module.addImport("telegram", telegram_mod);
exe.linkLibC(); // Required for HTTP client
Option 3: Direct Download
git clone https://github.com/Nyarum/zigtgshka.git
cd zigtgshka
Create src/main.zig
:
const std = @import("std");
const telegram = @import("telegram");
pub fn main() !void {
// 🏗️ Setup with explicit allocator (Zig best practice)
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer _ = gpa.deinit();
const allocator = gpa.allocator();
// 🌐 Initialize HTTP client
var client = try telegram.HTTPClient.init(allocator);
defer client.deinit();
// 🤖 Create your bot
var bot = try telegram.Bot.init(allocator, "YOUR_BOT_TOKEN", &client);
defer bot.deinit();
// 🎉 Get bot info and start polling
const me = try telegram.methods.getMe(&bot);
defer me.deinit(allocator);
std.debug.print("🚀 Bot @{s} is online!\n", .{me.username orelse me.first_name});
// 🔄 Simple polling loop
var offset: i32 = 0;
while (true) {
const updates = try telegram.methods.getUpdates(&bot, offset, 100, 30);
defer {
for (updates) |*update| update.deinit(allocator);
allocator.free(updates);
}
for (updates) |update| {
offset = update.update_id + 1;
if (update.message) |message| {
if (message.text) |text| {
// 💬 Echo messages back
const reply = try telegram.methods.sendMessage(&bot, message.chat.id, text);
defer reply.deinit(allocator);
std.debug.print("📨 Echoed: {s}\n", .{text});
}
}
}
}
}
Run it:
# Using zig build (recommended)
zig build run
# Or build and run manually
zig build
./zig-out/bin/my_bot
We provide comprehensive examples from beginner to advanced use cases:
📖 For detailed documentation of all examples, see examples/README.md
Example | Description | Complexity | Key Features |
---|---|---|---|
echo_bot | Simple echo bot | 🟢 Beginner | Basic message handling |
bot_info | Get bot information | 🟢 Beginner | API calls, error handling |
simple_sender | Send targeted messages | 🟡 Intermediate | Direct messaging |
polling_bot | Command-based bot | 🟡 Intermediate | Command parsing, help system |
advanced_bot | Full-featured bot | 🔴 Advanced | State management, analytics |
webhook_manager | Webhook setup | 🟡 Intermediate | Webhook configuration |
We welcome contributions! Here's how to get started:
# Clone the repository
git clone https://github.com/Nyarum/zigtgshka.git
cd zigtgshka
# Run tests to verify setup
zig build test
# Run examples to test functionality
make run-info API_KEY=your_test_token
- Code Style: Follow Zig's standard formatting (
zig fmt
) - Memory Safety: Always pair
init()
withdeinit()
- Error Handling: Use explicit error types and handling
- Documentation: Update docs for any API changes
- Tests: Add tests for new functionality
- Use the issue template
- Include Zig version (
zig version
) - Provide minimal reproduction code
- Include relevant log output
- Memory Usage: < 10MB for typical bots
- Latency: < 50ms average response time
- Throughput: 1000+ messages/second
- Binary Size: < 2MB (release builds)
- Zero-allocation hot paths
- Compile-time parameter validation
- Efficient JSON parsing with
std.json
- Connection pooling for HTTP requests
- Official Bot API Documentation
- BotFather - Create and manage bots
- Telegram Bot Examples
This project is licensed under the MIT License - see the LICENSE file for details.
Made with ❤️ and Zig
Star ⭐ this repo if you find it useful!