Morse

Morse is a client for Telegram Bot API for the Clojure programming language.

Installation

Add [morse "0.4.3"] to the dependency section in your project.clj file.

There is also a template which you can use to bootstrap your project:

lein new morse my-project
cd my-project
export TELEGRAM_TOKEN=...
lein run

Detecting user's actions

Telegram sends updates about events in chats in form of Update objects.

Inside those there could be commands, inline queries and many more. To help you with these Morse provides you helpers and some macros in morse.handlers namespace.

If you are familiar with building web-service with Compojure, you'll find similarities here:

(ns user
  (:require [morse.handlers :as h]
            [morse.api :as t]))

(def token "YOUR-BIG-SECRET")

; This will define bot-api function, which later could be
; used to start your bot
(h/defhandler bot-api
  ; Each bot has to handle /start and /help commands.
  ; This could be done in form of a function:
  (h/command-fn "start" (fn [{{id :id :as chat} :chat}]
                          (println "Bot joined new chat: " chat)
                          (t/send-text token id "Welcome!")))

  ; You can use short syntax for same purposes
  ; Destructuring works same way as in function above
  (h/command "help" {{id :id :as chat} :chat}
    (println "Help was requested in " chat)
    (t/send-text token id "Help is on the way"))

  ; Handlers will be applied until there are any of those
  ; returns non-nil result processing update.

  ; Note that sending stuff to the user returns non-nil
  ; response from Telegram API.

  ; So match-all catch-through case would look something like this:
  (h/message message (println "Intercepted message:" message)))

Messages

Receives Message object as first parameter in a function or target of binding:

(command-fn "start" (fn [msg] (println "Received command: " msg)))
; or in a macro form
(command "start" msg (println "Received command: " msg))

If you wish to process messages that are not prefixed by a command, there is also a helper:

(message-fn (fn [msg] (println "Received message: " msg)))
; or in a macro form
(message msg (println "Received message: " msg))

Inline requests

There is also a helper to define handlers for InlineQueries in a similar form:

(inline-fn (fn [inline] (println "Received inline: " inline)))
; or in a macro form
(inline inline (println "Received inline: " inline))

Callbacks

You can provide handlers for Callbacks which are sent from inline keyboards

(callback-fn (fn [data] (println "Received callback: " inline)))
; or in a macro form
(callback data (println "Received callback: " inline))

Starting your bot

As Telegram documentation says, there are two ways of getting updates from the bot: webhook and long-polling.

Webhook

If you develop a web application, you can use api call to register one of your endpoints in Telegram:

(require '[morse.api :as api])

(api/set-webhook "abc:XXX" "http://example.com/handler")

Telegram will use this url to POST messages to it. You can also use handler to react on these messages. Here is quick example if you use compojure:

(defhandler bot-api
  (command "help" {{id :id} :chat}
    (api/send-text token id "Help is on the way")))

(defroutes app-routes
  (POST "/handler" {{updates :result} :body} (map bot-api updates))
  (route/not-found "Not Found"))

Long-polling

This solution works perfectly if you don't plan on having a webserver or want to test your bot from a local machine.

Start the process by simply calling start function and pass it token and your handler:

(require '[morse.polling :as p])

(def channel (p/start token handler))

Then if you want to stop created background processes, call stop on returned channel:

(p/stop channel)

Sending messages

Use morse.api to interact with Telegram chats:

(require '[morse.api :as api])

Following methods from the API are implemented at the moment. All of them may use the advanced options by providing an additional option map argument. For all functions sending files File, ByteArray and InputStream are supported as arguments.

sendMessage

(api/send-text token chat-id "Hello, fellows")

You can use advanced options:

(api/send-text token chat-id
               {:parse_mode "Markdown"}
               "**Hello**, fellows")

sendPhoto

This sends a photo that will be displayed using the embedded image viewer where available.

(require '[clojure.java.io :as io])

(api/send-photo token chat-id
                (io/file (io/resource "photo.png")))

You can use advanced options:

(api/send-photo token chat-id
                {:caption "Here is a map:"}
                (io/file (io/resource "map.png")))

sendVideo

Sends the given mp4 file as a video to the chat which will be shown using the embedded player where available.

(api/send-video token chat-id
                (io/file (io/resource "video.mp4")))

sendAudio

Sends the given mp3 file as an audio message to the chat.

(api/send-audio token chat-id
                (io/file (io/resource "audio.mp3")))

sendSticker

Sends the given WebP image as a sticker to the chat.

(api/send-sticker token chat-id
                  (io/file (io/resource "sticker.webp")))

sendDocument

This method can be used for any other kind of file not supported by the other methods, or if you don't want telegram to make a special handling of your file (i.e. sending music as a voice message).

(api/send-document token chat-id
                   (io/file (io/resource "document.pdf")))

answerInlineQuery

Sends an answer to an inline query.

(api/answer-inline token inline-query-id options
                   [{:type "gif"
                     :id "gif1"
                     :gif_url "http://funnygifs/gif.gif"}])

answerCallbackQuery

Sends an answer to an callback query sent from inline keyboards.

(api/answer-callback token
                     callback-query-id
                     text
                     show-alert)

Q-Code

Q-Codes in Morse are shorthands for common patterns. morse.qcodes/direct-reply & morse.qcodes/req-morse are the Q-Codes already available. Here is an example usage of both.

(ns look.anotherbadlynamedns
  (:require [morse.qcodes :as q]
            [morse.handlers :as h]
            [somehttpserver :as http]))

(def token "")
(def webhook "")

(defn just-say-hi [name]
  (str "Hi " name "!"))

(defhandler thisismyapp
  (message {:keys [text]} (just-say-hi text)))

(def therealhandler (q/direct-reply token thisismyapp))

(morse.api/set-webhook token (str webhook "/" token)) ;; make webhooks safe by using the token as path
(def myserver (http/start-server (q/req->morse token therealhandler) {:port 80}))
;; req->morse will convert json to edn and make sure the proper path (token) is used.

License

Copyright © 2017 Anton Chebotaev

Distributed under the Eclipse Public License either version 1.0.