Skip to main content
Version: 0.0.2

telebot Framework

telebot is the first official documented framework package for RayQuiro. It targets the Telegram Bot API and ships as a framework, not as a built-in namespace.

Install​

Install from the approved registry:

rqio install telebot

Or install directly from GitHub:

rqio framework install RayQuiro/Telebot

What telebot Provides​

In 0.0.2, telebot supports:

  • text messages
  • HTML messages
  • Markdown messages
  • document sending
  • photo sending
  • inline buttons
  • callback handling
  • command registration
  • long polling through a generated PowerShell host

Quick Start​

from telebot import token_from_env, bot, on_command, on_button_command, on_callback, on_document_command, on_message, run_polling;

var token = token_from_env("TELEGRAM_BOT_TOKEN");
var app = bot(token, "build/telebot_demo");

on_command(app, "/start", "Welcome to RayQuiro Telebot.");
on_command(app, "/help", "Commands: /start /help /menu /doc");
on_button_command(app, "/menu", "Choose an action:", "Website=>https://raytolfas.com" + ";Support=>support_callback");
on_callback(app, "support_callback", "Support button clicked.");
on_document_command(app, "/doc", "README.md", "RayQuiro document demo");
on_message(app, "I got your message.");

run_polling(app);

Before running, set the bot token:

$env:TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"
rqio examples/telebot_demo.rq

run_polling(app) generates a PowerShell host script and starts long polling.

Bot Root​

bot(token, rootDir) prepares a bot workspace:

  • token.txt
  • handlers.rqtb
  • commands.rqtb
  • state.offset
  • bot.ps1

Example:

var app = bot(token, "build/mybot");

High-level Bot API​

Bot creation​

  • bot(token, rootDir)
  • bot_default(token)

Handler registration​

  • on_command(root, command, text)
  • on_command_html(root, command, html)
  • on_command_markdown(root, command, text)
  • on_message(root, text)
  • on_callback(root, callbackData, text)
  • on_photo_command(root, command, filePath, caption)
  • on_document_command(root, command, filePath, caption)
  • on_button_command(root, command, text, buttonsSpec)

Polling helpers​

  • build_polling(root)
  • run_polling(root)
  • stop_polling(root)

Button Specification​

on_button_command(...) uses a semicolon-separated inline button spec:

"Website=>https://example.com" + ";Support=>support_callback"

Rules:

  • Label=>https://... creates a URL button
  • Label=>callback_name creates a callback button

Low-level Telegram Helpers​

If you want direct API helpers, telebot also exposes raw command builders and utility functions.

Utility​

  • token_from_env(envName)
  • api_root(token)
  • file_root(token)
  • method_url(token, method)
  • file_url(token, telegramFilePath)

Raw command builders​

  • send_message_cmd(token, chatId, text)
  • send_html_cmd(token, chatId, html)
  • send_markdown_cmd(token, chatId, text)
  • reply_cmd(token, chatId, replyToMessageId, text)
  • send_photo_cmd(token, chatId, filePath, caption)
  • send_document_cmd(token, chatId, filePath, caption)
  • answer_callback_cmd(token, callbackId, text)
  • send_buttons_cmd(token, chatId, text, replyMarkupJson)
  • set_webhook_cmd(token, webhookUrl)
  • delete_webhook_cmd(token)
  • get_me_cmd(token, outputPath)
  • get_updates_cmd(token, offset, timeoutSeconds, outputPath)
  • get_file_cmd(token, fileId, outputPath)
  • download_file_cmd(token, telegramFilePath, outputPath)

Immediate helper calls​

  • send_message(...)
  • send_html(...)
  • send_markdown(...)
  • reply(...)
  • send_photo(...)
  • send_document(...)
  • answer_callback(...)
  • send_buttons(...)
  • set_webhook(...)
  • delete_webhook(...)
  • get_me(...)
  • get_updates(...)
  • get_file(...)
  • download_file(...)

Example: Direct Message Send​

from telebot import token_from_env, send_message;

var token = token_from_env("TELEGRAM_BOT_TOKEN");
send_message(token, "123456789", "Hello from RayQuiro!");

Example: Inspect The Raw Command​

from telebot import send_message_cmd;

print(send_message_cmd("TOKEN", "123456789", "Hello"));

How Polling Works​

run_polling(root) writes bot.ps1 and runs:

powershell.exe -ExecutionPolicy Bypass -File "<root>/bot.ps1"

The host script:

  • reads handlers from handlers.rqtb
  • syncs Telegram commands
  • polls getUpdates
  • routes commands, messages, and callbacks

Stop it with:

  • Ctrl+C
  • or stop_polling(root) to create a stop flag file

Current Limitations​

telebot is production-minded but still pragmatic in 0.0.2.

Important notes:

  • it relies on curl.exe
  • the polling host is PowerShell-based
  • the framework currently focuses on Windows-first flows
  • complex JSON handling is still routed through files and generated host logic rather than full native JSON objects inside the language

For the current release, it is already strong enough for:

  • simple bots
  • command bots
  • menu bots
  • file delivery bots