Tourmaline - Telegram Bot Framework For Crystal


Telegram Bot (and hopefully shortly Client) API framework for Crystal. Based heavily off of Telegraf this Crystal implementation allows your Telegram bot to live on written inwards a linguistic communication that's both beautiful in addition to fast. Benchmarks coming soon.
If you lot desire to extend your bot past times using NLP, run into my other library Cadmium.

Installation
Add this to your application's shard.yml:
dependencies:   tourmaline:     github: watzon/tourmaline     version:  > 0.7.0

Usage

Basic usage
require "tourmaline/bot"  alias TGBot = Tourmaline::Bot  bot = TGBot::Client.new(ENV["API_KEY"])  bot.command(["start", "help"]) practise |message|   text = "Echo bot is a sample bot created alongside the Tourmaline bot framework."   bot.send_message(message.chat.id, text) cease  bot.command("echo") practise |message, params|   text = params.join(" ")   bot.send_message(message.chat.id, text) cease  bot.poll

Listening for events
Tourmaline has a number of events that you lot tin heed for (the same events every bit Telegraf actually). The total listing of events is every bit tin live on works life in the documentation.
bot.on(:text) practise |update|   text = update.message.not_nil!.text.not_nil!   puts "TEXT: #{text}" end

Adding middleware
Middleware tin live on created past times extending the Tourmaline::Bot::Middleware class. All middleware classes demand to cause got a call(update : Update) method. The middleware volition live on called on every update.
class MyMiddleware < TGBot::Middleware    # All middlware include a reference to the rear 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}"         cease       cease     cease   cease  cease  bot.use MyMiddleware

Webhooks
Using webhooks is easy, fifty-fifty locally if you lot piece of employment the ngrok.cr package.
# bot.poll  bot.set_webhook("https://example.com/bots/my_tg_bot") bot.serve("0.0.0.0", 3400)  # or alongside ngrok.cr  require "ngrok"  Ngrok.start({ addr: "127.0.0.1:3400" }) practise |ngrok|   bot.set_webhook(ngrok.ngrok_url_https)   bot.serve("127.0.0.1", 3400) end

Payments
You tin straight off cause got payments alongside your Tourmaline app! First brand certain you lot follow the setup instructions here in addition to hence that your bot is prepared to handgrip payments. Then but piece of employment the send_invoice, answer_shipping_query, in addition to answer_pre_checkout_query methods to post invoices in addition to cause got payments.
bot.command("buy") practise |message, params|   bot.send_invoice(     message.chat.id,     "Sample Invoice",     "This is a test...",     "123344232323",     "YOUR_PROVIDER_TOKEN",     "test1",     "USD",     bot.labeled_prices([{label: "Sample", amount: 299}, {label: "Another", amount: 369}]).to_json   ) end

Games
Ability to practise in addition to run games alongside your Tourmaline Bot is a recent characteristic that hasn't been tested yet. Please piece of employment the issue tracker if you lot experience problems.

Kemal Middleware
Tourmaline provides middleware for Kemal, but inwards illustration you lot desire to piece of employment Kemal every bit the server.
require "kemal" require "tourmaline/kemal/tourmaline_handler"  require "./your_bot"  add_handler Kemal::TourmalineHandler.new(   bot: YourBot.new,   url: "https://something.com",   path: "/bot-webhook/#{ENV["TGBOT_API_KEY"]}" )  Kemal.run
Note: Telegram won't post webhook requests to non-ssl domains. This agency that you lot demand to live on running your kemal server alongside ssl enabled. For local evolution this tin live on a pain, but it is made much easier alongside ngrok.cr.

Development
This currently supports the next features:
  • Bot API
    • Implementation examples
    • Easy ascendancy syntax
    • Robust middleware system
    • Standard API queries
    • Stickers
    • Inline mode
    • Long polling
    • Webhooks
    • Payments
    • Games
  • Client API (in development)
If you lot desire a novel characteristic experience gratuitous to submit an number or opened upwards a delineate request.

Contributing
  1. Fork it ( https://github.com/watzon/tourmaline/fork )
  2. Create your characteristic branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add to a greater extent than or less feature')
  4. Push to the branch (git force source my-new-feature)
  5. Create a novel Pull Request

Contributors
  • watzon Chris Watson - creator, maintainer