Para hospedar um bot TelegramBots (Java) 24/7, você o executa em uma máquina que fica sempre ligada: uma VPS Linux com um serviço systemd que o inicia de novo quando ele para, ou um plano de bots na hospedagem de bots do Telegram da PlayNHost (a partir de US$1,99 por mês), onde você envia um jar executável, cola o token do @BotFather e aperta Start. No nosso teste, um bot com TelegramBots 10.3.0, a biblioteca Java de rubenlagus, usou cerca de 91 MB de memória no Java 21 e recebeu a resposta do Telegram 1,5 segundo depois de ser iniciado. Use o módulo de long polling: nossos planos ainda não têm um endereço HTTPS público para um webhook. Os passos na PlayNHost:
- Na página Hospedagem de bots do Telegram, clique em Criar servidor em um plano. Na janela do pedido, responda Para qual plataforma é o seu bot? com Telegram e escolha Java.
- No seu computador, compile o bot com o
pom.xmlabaixo:mvn packagegravatarget/bot.jar, com o TelegramBots dentro. - Abra seu servidor no painel. O cartão Configurar seu bot em Visão geral abre em Conectar ao Telegram; o primeiro passo, O que roda, deve dizer Este bot roda Java Bot.
- Em Conectar ao Telegram, cole o token em Cole o token do seu bot, clique em Conectar, confira o nome do bot exibido e clique em Sim, continuar.
- Em Seu código, clique em Enviar arquivos e envie
bot.jarpara a pasta principal. - Na página Bot, painel Código, confira se Arquivo de entrada é
bot.jare se Runtime é Java 21 (recommended), ou Java 17 ou 25. Se você mudar o Arquivo de entrada, clique em Salvar ao lado; um novo Runtime é salvo assim que você o escolhe. - Clique em Iniciar bot e abra Console. Quando seu bot imprimir
Logged in as @your_bot, o indicador em Visão geral muda para Online no Telegram. - Na página Bot, painel Telegram, clique em Abrir no Telegram e envie
/startao seu bot.
Como criar o bot no @BotFather e os passos do painel estão explicados em Como hospedar um bot do Telegram. Esta página trata do TelegramBots em si: o que ele usa em um servidor e o que saber antes de hospedá-lo.
O que medimos
| Biblioteca | Versão | Memória sem carga | Do início à resposta do Telegram | Tamanho do jar |
|---|---|---|---|---|
| TelegramBots (rubenlagus) | 10.3.0 | 91 MB | 1,5 s | 9,6 MB |
| Só o Java 21, sem biblioteca | 21.0.12.1 | 38 MB | nenhuma | 0,0 MB |
Como: no nosso próprio nó, em um contêiner descartável configurado como um plano de bots de 1 GB (a imagem do Java 21 e o comando java exato do nosso tipo de bot Java), o bot chamou getMe do Telegram com um token falso, que o Telegram recusou; a memória é a memória residente 15 segundos depois dessa resposta, o tempo de inicialização vai do início até a resposta, e cada valor é a mediana das execuções 2 a 4.
Esses são valores mínimos: ainda sem chats, sem dados e sem polling. Seu próprio código, o que ele guarda na memória e o número de chats se somam a eles, e o script de inicialização deixa o heap do Java crescer até 80 por cento do plano (veja abaixo). Compare os números com os planos da hospedagem de bots do Telegram e escolha conforme o que seu bot faz.
Um bot TelegramBots mínimo
Ele responde a /start, lê o token de TELEGRAM_BOT_TOKEN (o painel o entrega ao seu código com esse nome e também como BOT_TOKEN, TOKEN, TELEGRAM_TOKEN e TELOXIDE_TOKEN) e imprime uma linha de pronto. Dois arquivos:
pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>bot</artifactId>
<version>1.0</version>
<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>org.telegram</groupId>
<artifactId>telegrambots-longpolling</artifactId>
<version>10.3.0</version>
</dependency>
<dependency>
<groupId>org.telegram</groupId>
<artifactId>telegrambots-client</artifactId>
<version>10.3.0</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>2.0.12</version>
</dependency>
</dependencies>
<build>
<finalName>bot</finalName>
<plugins>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>3.7.1</version>
<configuration>
<descriptorRefs>
<descriptorRef>jar-with-dependencies</descriptorRef>
</descriptorRefs>
<appendAssemblyId>false</appendAssemblyId>
<archive>
<manifest>
<mainClass>Bot</mainClass>
</manifest>
</archive>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>src/main/java/Bot.java
import org.telegram.telegrambots.client.okhttp.OkHttpTelegramClient;
import org.telegram.telegrambots.longpolling.TelegramBotsLongPollingApplication;
import org.telegram.telegrambots.longpolling.util.DefaultLongPollingUpdateConsumer;
import org.telegram.telegrambots.meta.api.methods.GetMe;
import org.telegram.telegrambots.meta.api.methods.send.SendMessage;
import org.telegram.telegrambots.meta.api.objects.Update;
import org.telegram.telegrambots.meta.api.objects.User;
import org.telegram.telegrambots.meta.exceptions.TelegramApiException;
import org.telegram.telegrambots.meta.exceptions.TelegramApiRequestException;
import org.telegram.telegrambots.meta.generics.TelegramClient;
public class Bot extends DefaultLongPollingUpdateConsumer {
private final TelegramClient client;
Bot(TelegramClient client) {
this.client = client;
}
@Override
public void consume(Update update) {
if (update.hasMessage() && update.getMessage().hasText()
&& update.getMessage().getText().startsWith("/start")) {
SendMessage reply = SendMessage.builder()
.chatId(update.getMessage().getChatId())
.text("Hello! I am running on PlayNHost.")
.build();
try {
client.execute(reply);
} catch (TelegramApiException e) {
e.printStackTrace();
}
}
}
public static void main(String[] args) throws Exception {
String token = System.getenv("TELEGRAM_BOT_TOKEN");
if (token == null || token.isBlank()) {
System.out.println("No TELEGRAM_BOT_TOKEN found. Paste your bot token on the Bot page, then restart.");
System.exit(1);
}
TelegramClient client = new OkHttpTelegramClient(token);
User me = null;
try {
me = client.execute(new GetMe());
} catch (TelegramApiRequestException e) {
if (e.getErrorCode() != null && e.getErrorCode() == 401) {
System.out.println("Telegram did not accept the bot token. Paste the current one from @BotFather on the Bot page, then restart.");
System.exit(1);
}
throw e;
}
try (TelegramBotsLongPollingApplication app = new TelegramBotsLongPollingApplication()) {
// Long polling: registerBot removes a webhook left on the bot, then asks Telegram for messages.
app.registerBot(token, new Bot(client));
System.out.println("Logged in as @" + me.getUserName());
Thread.currentThread().join();
}
}
}Compile-o com Maven 3.9 e um JDK 17 ou mais novo, e teste o jar no seu computador:
mvn package
java -jar target/bot.jarSem token, ele imprime No TELEGRAM_BOT_TOKEN found. e para, o que prova que o jar inicia e encontra sua classe principal. Envie target/bot.jar. Pare qualquer cópia que você execute no seu computador com o token real antes de iniciar a do servidor, ou as duas cópias recebem erros 409 Conflict do Telegram.
A chamada getMe confere o token antes de o polling começar e fornece o nome de usuário do bot para a linha de pronto. Logged in as @your_bot é a linha que muda o indicador para Online no Telegram.
Se o token estiver errado
No nosso teste, com um token falso, a chamada getMe do TelegramBots falhou com este erro:
TelegramApiRequestException: Error executing org.telegram.telegrambots.meta.api.methods.GetMe query: [401] UnauthorizedO bot acima captura essa recusa (código de erro 401) e imprime no lugar Telegram did not accept the bot token. Paste the current one from @BotFather on the Bot page, then restart. O painel lê essa linha e mostra o aviso O Telegram não aceitou o token do seu bot acima de Console. Para corrigir, no @BotFather envie /mybots, escolha seu bot, depois API Token, e copie o token de novo. Na página Bot, painel Telegram, clique em Substituir token, cole-o, clique em Salvar token e depois em Reiniciar agora.
O que saber sobre o TelegramBots em um servidor
- Versões: o TelegramBots 10.3.0 saiu em 7 set 2026 e oferece suporte à Bot API 10.3 do Telegram. Ele exige Java 17 ou mais novo, então todo Runtime que o painel oferece (Java 17, 21 ou 25) o executa.
- Dois pacotes, diferente dos tutoriais antigos. Desde a versão 7.0.0 (março de 2024), a biblioteca vem como
telegrambots-longpolling, que recebe mensagens, etelegrambots-client, que as envia. Os tutoriais que estendemTelegramLongPollingBotforam escritos para o pacote antigotelegrambots, lançado pela última vez como 6.9.7.1; essa classe não existe no 10.3.0, então o código deles não compila com ela. - Use long polling. A biblioteca também tem um módulo de webhook, mas um webhook precisa de um endereço HTTPS público, que nossos planos ainda não incluem. O
registerBotdo módulo de long polling chamadeleteWebhookantes de começar, então um webhook deixado por um host antigo é removido e as mensagens em espera são mantidas. Se você está vindo de um host com webhook: Como migrar um bot do Telegram para a PlayNHost. - Adicione uma biblioteca de logs, ou a biblioteca fica em silêncio. O TelegramBots registra logs pelo SLF4J. Sem um provedor SLF4J no seu jar, o SLF4J imprime um aviso uma vez e depois descarta cada linha de log da biblioteca, inclusive os erros do polling. O
pom.xmlacima adiciona oslf4j-simple, que escreve as linhas da biblioteca do nível INFO para cima na saída de erro padrão, então elas aparecem no Console. - Erros de polling são repetidos, não lançados. Quando uma chamada
getUpdatesfalha, o TelegramBots registraError received from Telegram GetUpdates Request, retrying in ... millise tenta de novo, então o processo continua rodando. A espera começa em cerca de meio segundo e cresce pela metade a cada vez até cerca de um minuto (com uma variação aleatória, até 90 segundos); quando passam 15 minutos sem uma chamada bem-sucedida, ele espera 15 minutos entre as tentativas. Por isso, depois de corrigir a causa, reinicie o bot em vez de esperar. Só o código de status HTTP, na linhaCaused bydo stack trace logo abaixo, diz o que deu errado; a descrição do erro do próprio Telegram não é impressa. Como oregisterBotjá removeu qualquer webhook, um 409 ali provavelmente significa que outra cópia do bot está fazendo polling com o mesmo token: pare-a. Veja Como corrigir o erro 409 Conflict do bot do Telegram. - A lição oficial, atualizada: ela implementa
LongPollingSingleThreadUpdateConsumer, que o 10.3.0 marca como obsoleta em favor da classeDefaultLongPollingUpdateConsumerusada acima; as duas tratam as atualizações uma de cada vez em uma thread em segundo plano. A linha de pronto dela,MyAmazingBot successfully started!, não muda o indicador para Online no Telegram: imprima uma linha que comece comLogged in as, como acima. - Mantenha
main()esperando. O polling roda nas threads da própria biblioteca; a lição terminamain()comThread.currentThread().join()para o programa não acabar, e o bot acima faz o mesmo. - Limite de memória: o script de inicialização executa o Java com
-XX:MaxRAMPercentage=80.0e o coletor de lixo G1, então o heap pode usar até 80 por cento da memória do seu plano. Se ele encher, o Java imprimejava.lang.OutOfMemoryErrore o painel mostra Seu bot ficou sem memória. - Um jar, nada instalado no servidor. O tipo de bot Java inicia
java -jarno seu Arquivo de entrada e não tem um campo Pacotes, então tudo precisa estar dentro do jar. Envie um novo jar para atualizar o bot.
Hospede você mesmo em uma VPS Linux
Uma VPS precisa só de um runtime Java, porque você compila o jar no seu próprio computador. No Debian 13 ou no Ubuntu 24.04, instale o Java 21; o Debian 12 traz o Java 17, que também executa o jar acima:
sudo apt update
sudo apt install openjdk-21-jre-headless
java -versionCrie um usuário para o bot e copie o jar para o servidor (por exemplo com scp), depois para a pasta dele:
sudo useradd --system --create-home --home-dir /opt/mybot mybot
sudo cp bot.jar /opt/mybot/
sudo chown -R mybot: /opt/mybotMantenha o token fora do seu código, em um arquivo que só o root pode ler:
sudo sh -c 'echo "TELEGRAM_BOT_TOKEN=123456789:your-token" > /etc/mybot.env'
sudo chmod 600 /etc/mybot.envCrie /etc/systemd/system/mybot.service:
[Unit]
Description=TelegramBots Telegram bot
Wants=network-online.target
After=network-online.target
[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/usr/bin/java -XX:MaxRAMPercentage=80.0 -jar /opt/mybot/bot.jar
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.targetInicie-o agora e a cada boot, e depois acompanhe a saída dele:
sudo systemctl daemon-reload
sudo systemctl enable --now mybot
sudo journalctl -u mybot -fRestart=always inicia o bot de novo 5 segundos depois de ele terminar ou travar, mas não depois de você pará-lo com systemctl stop. Em uma VPS, -XX:MaxRAMPercentage é uma parte da memória da máquina inteira, então reduza-o se outros programas rodarem ali. Para atualizar, copie o novo jar sobre o antigo e execute sudo systemctl restart mybot.
Hospedagem própria ou plano de bots
Em uma VPS que você mesmo gerencia, você cuida de:
- Atualizações e segurança do sistema operacional, e upgrades do Java.
- Copiar cada novo jar, o arquivo de serviço, o arquivo do token e as permissões dele.
- Ler o
journalctlpara descobrir por que o bot parou ou parou de responder. - Backups de tudo que seu bot armazena.
Em troca, uma VPS executa qualquer coisa, e você pode dar a ela um domínio com HTTPS para um webhook.
Em um plano de bots da PlayNHost, o painel faz isso por você:
- Java 17, 21 ou 25 em um seletor, com o limite de heap e o coletor de lixo já definidos.
- O token, conferido com o Telegram antes de ser salvo, guardado criptografado e entregue ao seu código com cinco nomes.
- Reiniciar o bot depois de uma falha. Se ele falhar de novo em menos de um minuto, fica parado e o Console diz o motivo.
- Um botão Remover webhook no painel Telegram e avisos acima do Console que nomeiam a causa, como um token recusado ou falta de memória.
- Envio pelo navegador e backups pelo painel.
Perguntas frequentes
Meu bot TelegramBots roda, mas não responde nada e não imprime nada. Por quê?
Na maioria das vezes o jar não tem um provedor SLF4J, então as próprias linhas de erro da biblioteca são descartadas enquanto ela continua tentando. Adicione o slf4j-simple como no pom.xml acima, compile de novo e olhe o Console. Um 409 repetido significa que outra cópia do bot está fazendo polling com o mesmo token; um 401 repetido significa que o token foi revogado no @BotFather. Depois de corrigir, reinicie o bot: a espera do TelegramBots entre as tentativas pode chegar a 15 minutos.
Posso usar o módulo de webhook do TelegramBots?
Ainda não nos nossos planos: um webhook precisa de um endereço HTTPS público, que eles não incluem. O long polling não precisa de nenhum, porque o bot pede ao Telegram as mensagens novas. Use telegrambots-longpolling como nesta página.
O TelegramBots precisa de um plano maior que um bot em Python ou Node.js?
Não por causa da biblioteca em si. No mesmo teste, executado do mesmo jeito, o TelegramBots usou 91 MB, o python-telegram-bot 22.8 usou 44 MB, o grammY 1.46.0 usou 60 MB e o aiogram 3.31.0 usou 173 MB, todos bem abaixo dos 0,5 GB do menor plano. O que seu bot guarda na memória decide o resto. No Java, a memória também depende do heap: o script de inicialização deixa ele crescer até 80 por cento do plano, e o coletor de lixo decide quanto disso é usado.
Qual versão do Java devo escolher?
Java 21, a recomendada, a menos que seu próprio código precise do 25. O TelegramBots 10.3.0 exige Java 17 ou mais novo. Compile com um release que não seja mais novo que o Runtime escolhido: um jar compilado para um Java mais novo para com UnsupportedClassVersionError.
Pronto para deixar seu bot TelegramBots rodando o dia todo? Veja os planos na hospedagem de bots do Telegram.
