Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

ggram Telegram Bot Framework

NEED TRANSLATORS. Please, make pull requests if you wanna help. Temporarily I recommend deepl to translate this page

Create Telegram bots of any complexity in Lua

local bot = ggram("token")

bot.enable_polling() -- enables getUpdates loop

bot.command("start", function(ctx)
	ctx.reply.text("Hello @" .. ctx.from.username)

Additional examples can be found in /examples


Here (click) you can find links to running bots, as well as many ideas that can be implemented with this framework for your Garry's Mod server and much more. The possibilities are almost endless.


  • Can work both on pure Lua, and on the Garry's Mod server
  • Does NOT require any third-party .dll or WEB scripts
  • Very minimalistic and easily expandable
  • If Telegram adds methods that are not already in the bot, they are very easy to add with a 3-line module
  • Possibility sending animations, documents, images
  • Friends with the functional programming paradigm



Download this repository and go to the downloaded folder. You can take a look at the contents of the Dockerfile. It does not contain ggram itself. It installs the dependencies to make it work.

# create image
docker build -t ggramenv:latest .

# run example bot (echo.lua)
# dont forget to change bot token in the file
docker run -it \
	-e "LUA_PATH=/app/lua/?.lua;/app/lua/?/init.lua;;" \
	-v $PWD:/app ggramenv \
	lua app/examples/echo.lua


Linux / Mac

Install luarocks (package manager like apt but for lua)

sudo apt install luarocks # linux
# or
brew install luarocks # mac

Install ggram

luarocks install ggram # latest release
# or
luarocks install --server= ggram # just latest

Make and run bot:

  1. Create bot.lua file. You can choose any name for the file
  2. Paste the contents of /examples/echo.lua into the file
  3. Run file with lua bot.lua

If any error was occur, check the troubleshooting part below

Garry's Mod

  1. 苤郕訄訄邿迮 ggram 郋迣郋 迮郈郋郱邽郋邽 邽 訄郇郋赲邽迮 赲 /addons/ggram
  2. 苤郋郱迡訄邿迮 訄邿郅 /addons/ggram_bots/lua/ggram/bots/anyname/_init.lua
  3. 訄郈郋郅郇邽迮 迮迣郋 郋迡迮迠邽邾邾 迡迮邾郋郇訄邽赲郇郋迣郋 訇郋訄 邽郱 郈訄郈郕邽 /examples, 郕訄郱訄赲 郋郕迮郇 @BotFather


Development tips and tricks

迮 訄郕訄郅郇郋 迡郅 Garry's Mod


If you plan to create several bots, then instead of using separate files for each bot, you can use one file, which will run all the other bots about this scheme:

-- Optionally, the path to the folder with the modules
package.path = string.format("%s;%s;%s",

-- Inluding ggram

-- List of bot code files
local bots = {"bot_file1", "bot_file2"}
for _,bot_name in ipairs(bots) do
	assert(pcall(require, bot_name))
	print(bot_name .. " loaded")


Only one polling server

郅 迮, 郕郋 郋迮 訄訇郋訄 郕迮邿 訇郋郋赲 訇迮郱 郅邽郇郋迣郋 赲迮訇 迮赲迮訄

迡迮郅訄郅 邾邽郕郋迮赲邽, 郕郋郋邿 郈邽郇邽邾訄迮 赲迮訇郕邽 郋 訄郱郇 迮赲邽郋赲, 訄 訄邾 赲郈訄迮 赲 郕訄迮赲迮 polling 迮赲迮訄, 郈郋迡郋訇郇郋 郕訄郕 訄訇郋訄迮 getUpdates 赲 Telegram. 迮 訇郋 郋郈訄赲郅 迮邾 郋訇郇郋赲郅迮郇邽, 郱訄迮邾 HTTP GET 郱訄郈郋郋邾 郈郋郅訄 邽 赲 郋迡郇郋邾 邾迮迮.

郅 訄訇郋 邽邾 迮赲邽郋邾 郇訄郈邽訄郅 郇迮訇郋郅郋邿 迮邿邾赲郋郕 邽 迮郅邽 迡郅 赲訄 郋 邽郇迮迮郇郋, 郋 邾郋迣 郋郈訇郅邽郕郋赲訄 迣訄邿迡, 郕訄郕 迮迣郋 郈邽邾迮郇邽.


VSCode 邽邾迮迮 郋迮郇 郕郋邿 赲郋迮郇郇邿 迡迮訇訄迣迣迮. 郅邽 訄郇郋赲邽 迡郅 郇迮迣郋 Lua Debug 郈郅訄迣邽郇, 郋 迮迣郋 郈郋邾郋 迡郋訇郇迮迮 郱訄郇邽邾訄 訄郱訄訇郋郕郋邿


Take a look here

If you still have problems, you can ask me in Telegram @amd_nick or create an Issue, in which you need to specify the system version, the version of lua -v, and step by step the actions you have taken to reproduce