Updates receiving

Long polling

Long polling is used by default. You don't need any movement to make the bot work.

It can be configured easy:

val config = TelegramBotConfig().apply {
    receiving {
        longPolling {
            limit = 10 // default null
            timeout = 25 // default 30
            retryDelay = 5_000 // default 5,000
            // default CoroutineScope(Dispatchers.Default + SupervisorJob() + CoroutineName("TelegramBot"))
            scope = CoroutineScope(Dispatchers.Default.limitedParallelism(10) + SupervisorJob())
        }
    }
}

That`s all. Bot works.

Webhook

It available only for web frameworks (Spring and Ktor). *But don't get too upset. More details in "Custom receiver".

You can configure it easily:

            telegram-bot:
                spring:
                    update-receiver: webhook
                    # URL to your bot application
                    update-receiver.webhook.url.host: "https://my.domain.com/api/my-awesome-bot"
        

By default, a unique random token will be generated for the X-Telegram-Bot-Api-Secret-Token header. By default, the full URL will be: https://my.domain.com/api/my-awesome-bot/updates/receive

All available properties:

PROPERTY	DEFAULT	DESCRIPTION
`telegram-bot.spring.update-receiver`	`long-polling`	Choosing `long polling` or `webhook`
`telegram-bot.spring.update-receiver.webhook.url.host`	-	Required: Base URL of your application. Will be concatenated with `url.path`.
`telegram-bot.spring.update-receiver.webhook.url.path`	`/updates/receive`	API endpoint path. Will be appended to host
`telegram-bot.spring.update-receiver.webhook.certificate.path`	-	Path to certificate (e.g. `/cert.pem`)
`telegram-bot.spring.update-receiver.webhook.ip-address`	-	Fixed IP instead of DNS-resolved
`telegram-bot.spring.update-receiver.webhook.max-connections`	-	Maximum simultaneous HTTPS connections
`telegram-bot.spring.update-receiver.webhook.drop-pending-updates`	-	true = drop all unprocessed updates
`telegram-bot.spring.update-receiver.webhook.secret-token`	-	Custom token for `X-Telegram-Bot-Api-Secret-Token` header
`telegram-bot.spring.update-receiver.webhook.secret-token.random-generation`	`RANDOM_UUID`	Token generation: `NONE`, `RANDOM_UUID`, `RANDOM_256_CHARS`
`telegram-bot.spring.update-receiver.webhook.secret-token.random-generation.print-on-startup`	`false`	true = print generated token on startup

More details: Telegram official docs: setWebhook

You can configure it easily:

            install(TelegramBot) {
                receiving {
                    webhook {
                        urlHost = "https://my.domain.com/api/my-awesome-bot"
                    }
                }
            }
        

By default, a unique random token will be generated for the X-Telegram-Bot-Api-Secret-Token header. By default, the full URL will be: https://my.domain.com/api/my-awesome-bot/updates/receive

All available properties:

PROPERTY	DEFAULT	DESCRIPTION
`urlHost`	-	Required: Base URL of your application. Will be concatenated with `url.path`.
`urlPath`	`/updates/receive`	API endpoint path. Will be appended to host
`certificate`	-	ContentInput file of certificate (e.g. path `/cert.pem`)
`ipAddress`	-	Fixed IP instead of DNS-resolved
`maxConnections`	-	Maximum simultaneous HTTPS connections
`dropPendingUpdates`	-	true = drop all unprocessed updates
`secretToken`	-	Custom token for `X-Telegram-Bot-Api-Secret-Token` header
`secretTokenRandomGeneration`	`RANDOM_UUID`	Token generation: `NONE`, `RANDOM_UUID`, `RANDOM_256_CHARS`
`secretTokenRandomGenerationPrintOnStartup`	`false`	true = print generated token on startup

More details: Telegram official docs: setWebhook

Custom receiver

And you can implement custom receiver (long polling or webhook, whatever you want).

class CustomUpdateReceiver(
    private val bot: TelegramBot,
    private val updateResolver: UpdateResolver,
    private val config: CustomConfig,
) : UpdateReceiver {

    private val logger: Logger = LoggerFactory.getLogger(CustomUpdateReceiver::class.java)

    override fun start(): Unit = runBlocking(Dispatchers.Default) {
        // Starting your bot
        // Calling bot.getUpdates() or bot.setWebhook()
        logger.info("Started custom update receiver.")
    }

    // Calling updateResolver.processUpdate()

    override fun stop(): Unit = runBlocking(Dispatchers.Default) {
        // Stopping your bot
        // Calling bot.deleteWebhook() or stopping client with long polling
        logger.info("Stopped custom update receiver.")
    }
}

val config = TelegramBotConfig().apply {
    // other settings

    receiving {
        updateReceiver = { CustomUpdateReceiver(telegramBot, receiving.updateResolver, CustomConfig()) }
    }
}

You can find examples in LongPollingUpdateReceiver and WebhookUpdateReceiver.

Last modified: 09 November 2025