BSD-3-Clause licensed by Alexey Rodiontsev
Maintained by [email protected]
This version can be pinned in stack with:telegram-api-0.6.0.0@sha256:ca961b5a8a444ec984cdb2d452cfbc850013dc7b389c670478c43739ef1c0057,3638

telegram-api

Join the chat at https://gitter.im/klappvisor/haskell-telegram-api

Build Status Hackage Hackage Dependencies Haskell Programming Language BSD3 License

High-level bindings to the Telegram Bot API based on servant library. Both getUpdates request or webhook can be used to receive updates for your bot. Inline mode is supported. Uploading stickers, documents, video, etc is not supported yet, but you can send items which are already uploaded on the Telegram servers.

Support of Bot-2.0 API

Usage

There are two ways of using Telegram Bot API. First and original way is to run IO directly for every Telegram servers request, another one is based on TelegramClient which is just ReaderT.

Use TelegramClient

{-# LANGUAGE OverloadedStrings #-}

import           Network.HTTP.Client      (newManager)
import           Network.HTTP.Client.TLS  (tlsManagerSettings)
import           Web.Telegram.API.Bot
import           Control.Monad            (when)

main :: IO ()
main = do
  let token = Token "bot<token>" -- entire Token should be bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
  manager <- newManager tlsManagerSettings
  result <- runClient ( do
    info <- getWebhookInfoM
    let request = setWebhookRequest' "https://example.com/hook"
    isSet <- setWebhookM request
    getMeM) token manager
  print result
  print "done!"

Runing IO directly

getMe example

{-# LANGUAGE OverloadedStrings #-}

import           Network.HTTP.Client      (newManager)
import           Network.HTTP.Client.TLS  (tlsManagerSettings)
import           Web.Telegram.API.Bot

main :: IO ()
main = do
  manager <- newManager tlsManagerSettings
  res <- getMe token manager
  case res of
    Left e -> do
      putStrLn "Request failed"
      print e
    Right Response { result = u } -> do
      putStrLn "Request succeded"
      print $ user_first_name u
  where token = Token "bot<token>" -- entire Token should be bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

sendMessage example

{-# LANGUAGE OverloadedStrings #-}

import           Network.HTTP.Client      (newManager)
import           Network.HTTP.Client.TLS  (tlsManagerSettings)
import           Web.Telegram.API.Bot

main :: IO ()
main = do
  manager <- newManager tlsManagerSettings
  let request = sendMessageRequest chatId message
  res <- sendMessage token request manager
  case res of
    Left e -> do
      putStrLn "Request failed"
      print e
    Right Response { result = m } -> do
      putStrLn "Request succeded"
      print $ message_id m
      print $ text m
  where token = Token "bot<token>" -- entire Token should be bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
        chatId = "<chat_id> or <@channelusername>"
        message = "text *bold* _italic_ [github](github.com/klappvisor/haskell-telegram-api)"

Note on requests:

Many request data records have a lot of optional parameters which are usually redundant. There are two ways to create requests:

With data type constructor:

let request = SendMessageRequest "chatId" "text" Nothing (Just True) Nothing Nothing Nothing

Using default instance:

let request = sendMessageRequest "chatId" "text" -- only with required fields
let request = (sendMessageRequest "chatId" "text") {
  message_disable_notification = Just True -- with optional fields
}

Contribution

Contributions are welcome!

  1. Fork repository
  2. Do some changes
  3. Create pull request
  4. Wait for CI build and review
  5. ??????
  6. PROFIT

Bear in mind that the CI build won’t run integration test suite against your pull request since the necessary environment variables ($BOT_TOKEN, $CHAT_ID and $BOT_NAME) aren’t exported when a fork starts the build (for security reasons). If you do want to run them before creating RP, you can setup integration of your fork with CircleCI.

You can use stack to build project

stack build

To run test you have to create your own bot. Go to BotFather and create the bot. As the result you will have private bot’s access token. Keep it safe!

stack test --test-arguments "--integration -t BOT_TOKEN -c CHAT_ID -b BOT_NAME -- HSPEC_ARGS"

where

  • BOT_TOKEN is the token obtained from BotFather
  • CHAT_ID can be id of your chat with your bot. Send some messages to this chat in Telegram and do curl "https://api.telegram.org/bot<replace_with_token>/getUpdates", you’ll have to parse some JSON with your brain ;-) or any other suitable tool and you will find chat id there.
  • BOT_NAME is the name of your bot
  • HSPEC_ARGS are the normal hspec arguments you can find here

The help option is available for the tests and for hspec:

stack test --test-arguments "-h"
stack test --test-arguments "--integration -t BOT_TOKEN -c CHAT_ID -b BOT_NAME -- -h"

Note: Inline Spec is disabled for now…

If everything is fine after running the tests you will receive a few new messages from your bot.

Changes

0.6.0.0

  • Added TelegramClient, see example of usage in README.md
  • Changes from December update of Telegram Bot API
  • TelegramBotAPI splitted in separate sub-types

0.5.2.0

Features:

  • Added webhook methods such as getWebhookInfo, deleteWebhook, etc.
  • Changes to update api
  • Added sendGame

0.5.1.1

Updated to use servant-0.9 and aeson-1.0

0.5.0.0 [Breaking]

Features:

  • [Breaking] Changed Response data record to be generic
  • Added certificate upload to set web-hook method for self-signed certificates

Bugfixes:

  • Removed O2 tag from cabal file

0.4.3.1

Bugfixes:

  • Exposed MessageEntity

0.4.3.0

Features:

  • Added Inline Keyboard to messages

0.4.2.0

Features:

  • Bot-2.1 support
    • Added new methods: getChat, leaveChat, getChatAdministrators, getChatMember, getChatMembersCount.
    • Added support for edited messages and new mentions from Telegram v.3.9. New fields: edited_message in Update, edit_date in Message, user in MessageEntity. New value text_mentionfor the type field inMessageEntity`.

0.4.1.0

Features:

  • Implemented file uploading for audio, voice, sticker, video and documents

Bugfixes:

  • Exposed constrictors for inline edit requests

0.4.0.1

Bugfixes:

  • Parsing issue with answer callback query response

0.4.0.0 [Breaking]

Features:

  • Bot-2.0 API support is almost complete. Everything from announce is on place except file upload (works for photo BTW).
    • Inline keyboards
    • Updating messages
    • Send Location and Phone number
    • Inline Bots 2.0
    • Group Admins
    • and many others
  • Added new and more convenient way to create request data records avoiding many optional parameters.
  • migrated to servant 0.7.*

0.3.1.0

Features:

  • Added possibility to upload and send photo

0.3.0.0

Bugfixes:

  • [Breaking] Changed User to be optional in from field of the Message data record since sender can be empty for messages sent to channels

0.2.1.1

Bugfixes:

  • Minor fix of chat action deserialization code

0.2.1.0

Features:

  • Added reply keyboard

0.2.0.0

Features:

  • Main functionality is on place except content upload.
  • Inline mode added