You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



Telegram Bot API wrapper for Scala

Version published



Idiomatic Scala wrapper for the Telegram Bot API


Simple, extensible, strongly-typed wrapper for the Telegram Bot API.

Table of contents

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.8.0"

// Extra goodies: Webhooks, support for games, bindings for actors.
libraryDependencies += "com.bot4s" %% "telegram-akka" % "5.8.0"

For mill add to your project deps:

ivy"com.bot4s::telegram-core:5.8.0", // core
ivy"com.bot4s::telegram-akka:5.8.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 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.

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._


RandomBot! (full example)
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 =>
  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 =>
      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 =
println("Press [ENTER] to shutdown the bot, it may take a few seconds...")
bot.shutdown() // initiate shutdown
// Wait for the bot end-of-life
Await.result(eol, Duration.Inf)
Google TTS (full example)

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"${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 =
println("Press [ENTER] to shutdown the bot, it may take a few seconds...")
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 = ""

  onCommand("lmgtfy") { implicit msg =>
    withArgs { args =>
        "" + URLEncoder.encode(args.mkString(" "), "UTF-8"),
        disableWebPagePreview = Some(true)

Check out the sample bots for more functionality.


This library uses Semantic Versioning. For the versions available, see the tags on this repository.


  • Alfonso² Peterssen - Owner/maintainer - :octocat: 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.

Buy Me A Coffee

Buy Me A Coffee

If you like this library, please consider buying me a coffee. :relaxed:


Package last updated on 29 Mar 2024

Did you know?


Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc