TelegramBotAPI

Docs
Useful repos
Misc
Platforms
Experimental Platforms

Hello! This is a set of libraries for working with Telegram Bot API.

Examples

There are several things you need to do to launch examples below:

• Add mavenCentral() to your project repositories
  • Maven variant
• Add dependency implementation "dev.inmo:tgbotapi:$tgbotapi_version"
  • Replace tgbotapi_version with exact version (see last one in the table above) or put variable with this name in project
  • Alternative variant for maven here

More including instructions available here. Other configuration examples:

• For multiplatform
• For JVM

Most common example

suspend fun main() {
  val bot = telegramBot(TOKEN)

  bot.buildBehaviourWithLongPolling {
    println(getMe())
  
    onCommand("start") {
      reply(it, "Hi:)")
    }
  }.join()
}

In this example you will see information about this bot at the moment of starting and answer with Hi:) every time it gets message /start

Handling only last messages

suspend fun main() {
  val bot = telegramBot(TOKEN)

  val flowsUpdatesFilter = FlowsUpdatesFilter()
  bot.buildBehaviour(flowUpdatesFilter = flowsUpdatesFilter) {
    println(getMe())
  
    onCommand("start") {
      reply(it, "Hi:)")
    }

    retrieveAccumulatedUpdates(this).join()
  }
}

The main difference with the previous example is that bot will get only last updates (accumulated before bot launch and maybe some updates it got after launch)

Build a little bit more complex behaviour

suspend fun main() {
  val bot = telegramBot(TOKEN)

  bot.buildBehaviourWithLongPolling {
    println(getMe())

    val nameReplyMarkup = ReplyKeyboardMarkup(
      matrix {
        row {
          +SimpleKeyboardButton("nope")
        }
      }
    )
    onCommand("start") {
      val photo = waitPhoto(
        SendTextMessage(it.chat.id, "Send me your photo please")
      ).first()

      val name = waitText(
        SendTextMessage(
          it.chat.id,
          "Send me your name or choose \"nope\"",
          replyMarkup = nameReplyMarkup
        )
      ).first().text.takeIf { it != "nope" }

      sendPhoto(
        it.chat,
        photo.mediaCollection,
        entities = buildEntities {
          if (name != null) regular(name) // may be collapsed up to name ?.let(::regular)
        }
      )
    }
  }.join()
}

More examples

You may find examples in this project. Besides, you are always welcome in our docs and chat.

Bot API Server Notice

Under the hood, default bots realizations will try to use links (PathedFile#filePath) as files each time you are trying to download file from telegram in any way - via saving to file, use stream or download as byte array. To let bot correctly download files from bot api server, you must:

• Run bot api server locally to proxy requests for files to the server where bot api server has been hosted
  • In case of local bot api server (shared one host machine) you must ensure that access to bot api server has been granted for your bot. For example, aiogram/telegram-bot-api image use 101 UID/GID in linux for user and group as owners. So, your bot must run under user included in 101 group (like systemd-journal) or be 101 UID user (like systemd-resolve)
• OR Use some reverse proxy (like nginx). It will allow you to broadcast your bots files without linux rights problems
  • Set TelegramAPIUrlsKeeper#fileLinkUrlMapper to map urls to let bot execute requests to your nginx proxy