vgram

vgram is a bot library for the Telegram Bot API written in V. The Bot API is an HTTP-based interface created for developers keen on building bots for Telegram.

It implements every type and method from Telegram Bot API 10.1.0. The V bindings (types.v, methods.v, vgram.v) are generated from the official API schema by the generator in gen/, so they can be regenerated whenever Telegram updates the API.

Installing

$ v install dariotarantini.vgram

Getting started

1. Search for the "@botfather" telegram bot and start it
2. Click on or type /newbot to create a new bot and follow his instructions
3. Copy the token and create a file named send_message.v with the following code:

module main

import dariotarantini.vgram

fn main() {
	bot := vgram.new_bot('TELEGRAM_BOT_TOKEN_HERE')
	bot.send_message(
		chat_id: 'USER_ID_HERE'
		text:    'yo! Made using vgram!'
	) or { panic(err) }
}

Examples

• hi_man.v - a complete Telegram bot written in V
• send_photo.v - uploading a local file via multipart/form-data

Documentation

You can find the documentation directly on the Telegram website, or read it in the vgram source code: see methods.v and types.v.

Call a method using:

result := bot_instance.method_name(
	method_arg1: 'some text'
	method_arg2: 123 // or int
)!

• bot_instance can be created using vgram.new_bot('TOKEN')
• method_name and method_args should be in snake_case
• every method returns a Result (!T): handle it with ! or or { ... }

Notes on the generated bindings

• Integer fields use i64 (Telegram chat / user ids exceed 32 bits).
• Large nested objects (e.g. Update.message, Message.reply_to_message) are optional references (?&Type); small structs like User/Chat stay values. Unwrap a reference once, then access values normally:

  if msg := update.message {
  	id := msg.from.id // `from` is a value, no further unwrapping
  }

  (References keep structs small; V's json decoder stack-allocates the whole struct tree, so embedding everything by value would overflow the stack.)
• Complex method parameters (objects, keyboards, media, unions) are typed as string; pass json.encode(...) of the relevant struct.

Errors

Every method returns !T. On failure you get either the underlying transport error, or a vgram.TelegramError when the API replies with ok: false:

msg := bot.send_message(chat_id: id, text: 'hi') or {
	if err is vgram.TelegramError {
		// err.code, err.description, err.retry_after, err.migrate_to_chat_id
		eprintln('telegram said: ${err.code} ${err.description}')
	}
	return err
}

TelegramError exposes retry_after (flood control / HTTP 429) and migrate_to_chat_id from Telegram's response parameters.

Configuration

Bot fields can be set after construction:

mut bot := vgram.new_bot('TOKEN')
bot.endpoint = 'http://localhost:8081/bot' // e.g. a local Bot API server
bot.timeout = 60 * time.second             // per-request read/write timeout (0 = no timeout)
bot.debug = true                           // log requests/responses to stderr
bot.headers['X-Custom'] = 'value'          // extra headers on every request

For API methods that don't have a generated helper yet, call them directly with the generic, public request method (it returns the raw JSON of the result field):

raw := bot.http_request('someNewMethod', json.encode(params))!

Uploading files

File parameters (photo, document, ...) accept a file_id or an HTTP URL as a plain string. To upload a local file, use http_request_files, which sends multipart/form-data:

import json

photo := vgram.input_file_from_path('cat.jpg')!
raw := bot.http_request_files('sendPhoto',
	{'chat_id': '123456', 'caption': 'look at this'},
	{'photo': [photo]})!
msg := json.decode(vgram.Message, raw)!

form holds the textual parameters (including the json.encode(...) of any complex ones, e.g. reply_markup); files maps each file field to its contents. input_file_from_path reads a file from disk; you can also build an http.FileData{filename, content_type, data} yourself.

Regenerating the bindings

The library files are produced from gen/botapi.json. To regenerate them (after updating the schema, for example):

v run gen                 # reads gen/botapi.json, writes types.v, methods.v, vgram.v at the module root
v run gen <schema> <dir>  # optional: custom input file and output directory

The generator formats its output with v fmt automatically.