Idiomatic Scala wrapper for the Telegram Bot API
-00aced.svg){kind=icon}
Simple, extensible, strongly-typed wrapper for the Telegram Bot API.
- Installation
- Quickstart with scala-cli
- Examples
- Leaking bot tokens
- Webhooks vs Polling
- Payments
- Games
- Deployment
- Running the examples
- A note on implicits
- Versioning
- Authors
- License
Since 6.0.0 telegram-core and telegram-akka are published for Scala 2.12, 2.13 and 3.
Add to your build.sbt file:
// Core with minimal dependencies, enough to spawn your first bot.
libraryDependencies += "com.bot4s" %% "telegram-core" % "6.0.0"
// Extra goodies: Webhooks, support for games, bindings for actors.
libraryDependencies += "com.bot4s" %% "telegram-akka" % "6.0.0"For mill add to your build.sc project deps:
// Core with minimal dependencies, enough to spawn your first bot.
ivy"com.bot4s::telegram-core:6.0.0",
// Extra goodies: Webhooks, support for games, bindings for actors.
ivy"com.bot4s::telegram-akka:6.0.0"Replace BOT_TOKEN with your Telegram bot token.
//> using scala 3.3.6
//> using dep "com.bot4s::telegram-core:6.0.0"
//> using dep "com.softwaremill.sttp.client3::okhttp-backend:3.11.0"
//
import cats.syntax.functor.*
import scala.concurrent.*
import scala.concurrent.duration.*
import com.bot4s.telegram.api.RequestHandler
import com.bot4s.telegram.clients.FutureSttpClient
import com.bot4s.telegram.future.*
import com.bot4s.telegram.methods.SendMessage
import com.bot4s.telegram.models.Message
import sttp.client3.SttpBackend
import sttp.client3.okhttp.OkHttpFutureBackend
/**
* Echo bot.
* Echo, ohcE
*/
class EchoBot(token: String) extends TelegramBot with Polling {
implicit val backend: SttpBackend[Future, Any] = OkHttpFutureBackend()
override val client: RequestHandler[Future] = new FutureSttpClient(token)
override def receiveMessage(msg: Message): Future[Unit] =
msg.text.fold(Future.successful(())) { text =>
request(SendMessage(msg.source, text.reverse)).void
}
}
@main def main() = {
// To run spawn the bot
val bot = new EchoBot("BOT_TOKEN")
val eol: Future[Unit] = 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)
}Random bot (full example)
class RandomBot(token: String) extends ExampleBot(token) with Polling with Commands[Future] {
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("/die" | "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
}
}
onCommand("auto") { implicit msg =>
request(SendDice(msg.chat.id)).void
}
// Extractor
object Int {
def unapply(s: String): Option[Int] = Try(s.toInt).toOption
}
}Text to speech bot (full example)
/**
* Text-to-speech bot (using Google TTS API)
*
* Google will rightfully block your IP in case of abuse.
* '''Usage:''' /speak Hello World
* '''Inline mode:''' @YourBot This is awesome
*/
class TextToSpeechBot(token: String)
extends ExampleBot(token)
with Polling
with Commands[Future]
with InlineQueries[Future]
with ChatActions[Future] {
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 ()
}
}
def nonEmptyQuery(iq: InlineQuery): Boolean = iq.query.nonEmpty
whenOrElse(onInlineQuery, nonEmptyQuery) { implicit iq =>
answerInlineQuery(
Seq(
// Inline "playable" preview
InlineQueryResultVoice("inline: " + iq.query, ttsUrl(iq.query), iq.query),
// Redirection to /speak command
InlineQueryResultArticle(
"command: " + iq.query,
iq.query,
inputMessageContent = InputTextMessageContent("/speak " + iq.query),
description = "/speak " + iq.query
)
)
).void
} /* empty query */ {
answerInlineQuery(Seq())(_).void
}
}Calculator bot (using Webhooks) (full example)
class WebhookBot(token: String) extends AkkaExampleBot(token) with Webhook {
val port = 8080
val webhookUrl = "https://88c444ab.ngrok.io"
val baseUrl = "http://api.mathjs.org/v1/?expr="
override def receiveMessage(msg: Message): Future[Unit] =
msg.text.fold(Future.successful(())) { text =>
val url = baseUrl + URLEncoder.encode(text, "UTF-8")
for {
res <- Http().singleRequest(HttpRequest(uri = Uri(url)))
if res.status.isSuccess()
result <- Unmarshal(res).to[String]
_ <- request(SendMessage(msg.source, result))
} yield ()
}
}Check out the sample bots for more functionality.
Don't ever expose your bot's token.
Hopefully GitGuardian got you covered and will warn you about exposed API keys.
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 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.
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.
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.
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 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._
This library uses Semantic Versioning. For the versions available, see the tags on this repository.
- 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.
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
If you like this library, please consider buying me a coffee.