Skip to content
Telegram Bot framework for Crystal
Branch: master
Clone or download
Latest commit b78933f Jun 17, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Some major refactoring Jun 17, 2019
examples Changed misspelling and updated ngrok example Jun 6, 2019
spec Build should pass Jun 17, 2019
src Build should pass Jun 17, 2019
.editorconfig Initial commit Feb 13, 2018
.gitignore Changed model namespacing, added lots of docs Jun 6, 2019
.travis.yml Added ameba Jun 17, 2019
LICENSE Initial commit Feb 13, 2018 Added travis badge Jun 17, 2019
shard.yml Added ameba Jun 17, 2019
tdlib.yml Lots of changes. Updated docs. Jun 6, 2019

Header Image

Travis (.org)

Telegram Bot (and hopefully soon Client) API framework for Crystal. Based heavily off of Telegraf this Crystal implementation allows your Telegram bot to be written in a language that's both beautiful and fast. Benchmarks coming soon.

If you want to extend your bot by using NLP, see my other library Cadmium.


Add this to your application's shard.yml:

    github: watzon/tourmaline
    version: ~> 0.7.0


Basic usage

require "tourmaline/bot"

alias TGBot = Tourmaline::Bot

bot =["API_KEY"])

bot.command(["start", "help"]) do |message|
  text = "Echo bot is a sample bot created with the Tourmaline bot framework."
  bot.send_message(, text)

bot.command("echo") do |message, params|
  text = params.join(" ")
  bot.send_message(, text)


Listening for events

Tourmaline has a number of events that you can listen for (the same events as Telegraf actually). The full list of events is as can be found in the documentation.

bot.on(:text) do |update|
  text = update.message.not_nil!.text.not_nil!
  puts "TEXT: #{text}"

Adding middleware

Middleware can be created by extending the Tourmaline::Bot::Middleware class. All middleware classes need to have a call(update : Update) method. The middleware will be called on every update.

class MyMiddleware < TGBot::Middleware

  # All middlware include a reference to the parent bot.
  # @bot : Tourmaline::Bot::Client

  def call(update : Update)
    if message = update.message
      if user = message.from_user
        if text = message.text
          puts "#{user.first_name}: #{text}"


bot.use MyMiddleware


Using webhooks is easy, even locally if you use the package.

# bot.poll

bot.serve("", 3400)

# or with

require "ngrok"

Ngrok.start({ addr: "" }) do |ngrok|
  bot.serve("", 3400)


You can now accept payments with your Tourmaline app! First make sure you follow the setup instructions here so that your bot is prepared to handle payments. Then just use the send_invoice, answer_shipping_query, and answer_pre_checkout_query methods to send invoices and accept payments.

bot.command("buy") do |message, params|
    "Sample Invoice",
    "This is a test...",
    bot.labeled_prices([{label: "Sample", amount: 299}, {label: "Another", amount: 369}]).to_json


Ability to create and run games with your Tourmaline Bot is a recent feature that hasn't been tested yet. Please use the issue tracker if you experience problems.

Kemal Middleware

Tourmaline provides middleware for Kemal, just in case you want to use Kemal as the server.

require "kemal"
require "tourmaline/kemal/tourmaline_handler"

require "./your_bot"

  url: "",
  path: "/bot-webhook/#{ENV["TGBOT_API_KEY"]}"

Note: Telegram won't send webhook requests to non-ssl domains. This means that you need to be running your kemal server with ssl enabled. For local development this can be a pain, but it is made much easier with


This currently supports the following features:

  • Bot API
    • Implementation examples
    • Easy command syntax
    • Robust middleware system
    • Standard API queries
    • Stickers
    • Inline mode
    • Long polling
    • Webhooks
    • Payments
    • Games
  • Client API (in development)

If you want a new feature feel free to submit an issue or open a pull request.


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


  • watzon Chris Watson - creator, maintainer
You can’t perform that action at this time.