Idiomatic Scala wrapper for the Telegram Bot API
bot4s.telegram
Simple, extensible, strongly-typed wrapper for the Telegram Bot API.
Table of contents
- Quick start
- Leaking bot tokens
- Webhooks vs Polling
- Payments
- Games
- Deployment
- Running the examples
- A note on implicits
- Examples
- Versioning
- Authors
- License
As SBT/mill dependency
Add to your build.sbt
file:
// Core with minimal dependencies, enough to spawn your first bot.
libraryDependencies += "com.bot4s" %% "telegram-core" % "5.7.0"
// Extra goodies: Webhooks, support for games, bindings for actors.
libraryDependencies += "com.bot4s" %% "telegram-akka" % "5.7.0"
For mill add to your build.sc
project deps:
ivy"com.bot4s::telegram-core:5.7.0", // core
ivy"com.bot4s::telegram-akka:5.7.0" // extra goodies
Leaking bot tokens
Don't ever expose your bot's token.
Hopefully GitGuardian got you covered and will warn you about exposed API keys.
Webhooks vs. Polling
Both methods are supported.
(Long) Polling is bundled in the core
artifact and it's by far the easiest method.
Webhook support comes in the extra
artifact based on akka-http; requires a server, it won't work on your laptop.
For a comprehensive reference check Marvin's Patent Pending Guide to All Things Webhook.
Some webhook examples are available here and here (with self signed SSL certificate setup).
Payments
Payments are supported since version 3.0; refer to official payments documentation for details. I'll support developers willing to integrate and/or improve the payments API; please report issues here.
Games
The Akka extensions include support for games in two flavors; self-hosted (served by the bot itself), and external, hosted on e.g. GitHub Pages. Check both the self-hosted and GitHub-hosted versions of the popular 2048 game.
Deployment
bot4s.telegram
runs on Raspberry Pi, Heroku, Google App Engine and most notably on an old Android (4.1.2) phone with a broken screen via the JDK for ARM.
Bots also runs flawlessly on top of my master thesis: "A meta-circular Java bytecode interpreter for the GraalVM".
Distribution/deployment is outside the scope of the library, but all platforms where Java is supported should be compatible. You may find sbt-assembly and sbt-docker very handy.
Scala.js is also supported, bots can run on the browser via the SttpClient. NodeJs is not supported yet.
Running the examples
bot4s.telegram
uses mill.
$ mill examples.jvm[2.13.10].console
[79/79] examples.jvm[2.13.10].console
Welcome to Scala 2.13.10 (OpenJDK 64-Bit Server VM, Java 11.0.10).
Type in expressions for evaluation. Or try :help.
scala> new RandomBot("BOT_TOKEN").run()
Change RandomBot
to whatever bot you find interesting here.
A note on implicits
A few implicits are provided to reduce boilerplate, but are discouraged because unexpected side-effects.
Think seamless T => Option[T]
conversion, Markdown string extensions (these are fine)...
Be aware that, for conciseness, most examples need the implicits to compile, be sure to include them.
import com.bot4s.telegram.Implicits._
Examples
(full example)
RandomBot!import cats.instances.future._
import cats.syntax.functor._
import com.bot4s.telegram.api.RequestHandler
import com.bot4s.telegram.api.declarative.Commands
import com.bot4s.telegram.clients.{FutureSttpClient, ScalajHttpClient}
import com.bot4s.telegram.future.{Polling, TelegramBot}
import slogging.{LogLevel, LoggerConfig, PrintLoggerFactory}
import scala.util.Try
import scala.concurrent.Future
/** Generates random values.
*/
class RandomBot(val token: String) extends TelegramBot
with Polling
with Commands[Future] {
LoggerConfig.factory = PrintLoggerFactory()
// set log level, e.g. to TRACE
LoggerConfig.level = LogLevel.TRACE
// Use sttp-based backend
implicit val backend = SttpBackends.default
override val client: RequestHandler[Future] = new FutureSttpClient(token)
// Or just the scalaj-http backend
// override val client: RequestHandler[Future] = new ScalajHttpClient(token)
val rng = new scala.util.Random(System.currentTimeMillis())
onCommand("coin" or "flip") { implicit msg =>
reply(if (rng.nextBoolean()) "Head!" else "Tail!").void
}
onCommand('real | 'double | 'float) { implicit msg =>
reply(rng.nextDouble().toString).void
}
onCommand("/dice" | "roll") { implicit msg =>
reply("⚀⚁⚂⚃⚄⚅" (rng.nextInt(6)).toString).void
}
onCommand("random" or "rnd") { implicit msg =>
withArgs {
case Seq(Int(n)) if n > 0 =>
reply(rng.nextInt(n).toString).void
case _ => reply("Invalid argumentヽ(ಠ_ಠ)ノ").void
}
}
onCommand('choose | 'pick | 'select) { implicit msg =>
withArgs { args =>
replyMd(if (args.isEmpty) "No arguments provided." else args(rng.nextInt(args.size))).void
}
}
// Int(n) extractor
object Int {
def unapply(s: String): Option[Int] = Try(s.toInt).toOption
}
}
// To run spawn the bot
val bot = new RandomBot("BOT_TOKEN")
val eol = bot.run()
println("Press [ENTER] to shutdown the bot, it may take a few seconds...")
scala.io.StdIn.readLine()
bot.shutdown() // initiate shutdown
// Wait for the bot end-of-life
Await.result(eol, Duration.Inf)
(full example)
Google TTSimport java.net.URLEncoder
import cats.instances.future._
import cats.syntax.functor._
import com.bot4s.telegram.Implicits._
import com.bot4s.telegram.api.declarative._
import com.bot4s.telegram.api.ChatActions
import com.bot4s.telegram.future.Polling
import com.bot4s.telegram.methods._
import com.bot4s.telegram.models._
import scala.concurrent.Future
/** Text-to-speech bot (using Google TTS API)
*
* Google will rightfully block your IP in case of abuse.
* Usage: /speak Hello World
*/
object TextToSpeechBot extends TelegramBot
with Polling
with Commands[Future]
with InlineQueries[Future]
with ChatActions[Future] {
override val client: RequestHandler[Future] = new ScalajHttpClient("BOT_TOKEN")
def ttsUrl(text: String): String =
s"http://translate.google.com/translate_tts?client=tw-ob&tl=en-us&q=${URLEncoder.encode(text, "UTF-8")}"
onCommand("speak" | "say" | "talk") { implicit msg =>
withArgs { args =>
val text = args.mkString(" ")
for {
r <- Future { scalaj.http.Http(ttsUrl(text)).asBytes }
if r.isSuccess
bytes = r.body
_ <- uploadingAudio // hint the user
voiceMp3 = InputFile("voice.mp3", bytes)
_ <- request(SendVoice(msg.source, voiceMp3))
} yield ()
}
}
}
val bot = TextToSpeechBot
val eol = bot.run()
println("Press [ENTER] to shutdown the bot, it may take a few seconds...")
scala.io.StdIn.readLine()
bot.shutdown() // initiate shutdown
// Wait for the bot end-of-life
Await.result(eol, Duration.Inf) // ScalaJs wont't let you do this
Using webhooks
object LmgtfyBot extends AkkaTelegramBot
with Webhook
with Commands[Future] {
val client = new AkkaHttpClient("BOT_TOKEN")
override val port = 8443
override val webhookUrl = "https://1d1ceb07.ngrok.io"
onCommand("lmgtfy") { implicit msg =>
withArgs { args =>
reply(
"http://lmgtfy.com/?q=" + URLEncoder.encode(args.mkString(" "), "UTF-8"),
disableWebPagePreview = Some(true)
)
}
}
}
Check out the sample bots for more functionality.
Versioning
This library uses Semantic Versioning. For the versions available, see the tags on this repository.
Authors
- Alfonso² Peterssen - Owner/maintainer - mukel
Looking for maintainers!
See also the list of awesome contributors who participated in this project. Contributions are very welcome, documentation improvements/corrections, bug reports, even feature requests.
License
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
Buy Me A Coffee
If you like this library, please consider buying me a coffee.