Sim: você consegue criar um bot funcional no Telegram com Python sem instalar uma biblioteca específica. O caminho mais simples é registrar o bot no @BotFather, guardar o token com segurança e usar a Bot API para ler mensagens e enviar respostas. Neste tutorial, vamos montar um bot de eco que também responde aos comandos /start e /id.
O exemplo usa apenas módulos que já vêm com o Python. Ele recebe atualizações por long polling — uma consulta HTTPS que fica esperando novas mensagens — e responde pelo método sendMessage. Isso é suficiente para aprender a lógica, automatizar tarefas pequenas e criar uma base para integrações maiores, sem fingir que um script curto já é um sistema de atendimento completo.
O que você vai construir
O bot deste guia vai:
- responder a
/start; - mostrar o identificador da conversa com
/id; - repetir qualquer texto enviado, como um eco;
- continuar funcionando enquanto o programa estiver aberto.
Ele não terá banco de dados, painel administrativo, autenticação de usuários nem conexão com inteligência artificial. Essa limitação é proposital: primeiro você entende o caminho entre Telegram, código e resposta. Depois pode trocar a mensagem fixa por uma consulta a uma API, uma planilha ou um sistema interno.
Antes de começar
- uma conta no Telegram;
- Python instalado no computador;
- um editor de texto ou IDE;
- um terminal para executar o arquivo.
A documentação oficial do Telegram explica que bots são contas especiais ligadas a um programa do proprietário e que não conseguem iniciar uma conversa: a pessoa precisa abrir o bot e enviar uma mensagem primeiro. A API é acessada por HTTPS e devolve respostas em JSON. A página consultada em 21 de agosto de 2026 também lista a Bot API 10.2, mas este tutorial usa métodos básicos que formam a base do fluxo.
1. Crie o bot no BotFather
- Abra o Telegram e procure por @BotFather.
- Envie o comando
/newbot. - Informe um nome de exibição para o bot.
- Escolha um nome de usuário único. Em geral, ele termina com
bot. - Copie o token entregue pelo BotFather.
O token funciona como uma senha: quem o possui pode controlar o bot pela API. Não coloque esse valor em um repositório público, em uma captura de tela ou diretamente no código que será compartilhado. Se ele vazar, use o próprio BotFather para revogá-lo e gerar outro.
2. Guarde o token em uma variável de ambiente
No Linux ou no macOS, abra o terminal na pasta do projeto e execute:
export TELEGRAM_BOT_TOKEN='COLE_SEU_TOKEN_AQUI'No PowerShell do Windows, use:
$env:TELEGRAM_BOT_TOKEN = 'COLE_SEU_TOKEN_AQUI'Esses comandos valem apenas para a sessão atual do terminal. É uma escolha mais segura do que salvar o segredo no arquivo bot.py. Em um servidor, configure a variável no gerenciador de processos ou no serviço de hospedagem.
3. Escreva o código do bot
Crie um arquivo chamado bot.py e cole o código abaixo:
import json
import os
import time
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen
TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
BASE_URL = f"https://api.telegram.org/bot{TOKEN}/"
def telegram_call(method, params=None):
data = urlencode(params or {}).encode("utf-8")
request = Request(
BASE_URL + method,
data=data,
headers={"Content-Type": "application/x-www-form-urlencoded"},
)
with urlopen(request, timeout=70) as response:
payload = json.load(response)
if not payload.get("ok"):
raise RuntimeError(payload.get("description", "Erro desconhecido na API"))
return payload["result"]
def main():
offset = None
print("Bot online. Pressione Ctrl+C para parar.")
while True:
params = {"timeout": 50, "limit": 100}
if offset is not None:
params["offset"] = offset
try:
updates = telegram_call("getUpdates", params)
for update in updates:
# Confirma a atualização somente depois de recebê-la.
offset = update["update_id"] + 1
message = update.get("message")
if not message or "text" not in message:
continue
chat_id = message["chat"]["id"]
text = message["text"].strip()
if text == "/start":
reply = "Olá! Eu sou um bot feito em Python."
elif text == "/id":
reply = f"O chat_id desta conversa é {chat_id}."
else:
reply = f"Você disse: {text}"
telegram_call(
"sendMessage",
{"chat_id": chat_id, "text": reply},
)
except (HTTPError, URLError, TimeoutError) as error:
print(f"Falha temporária: {error}. Tentando novamente...")
time.sleep(3)
if __name__ == "__main__":
main()
O programa faz três coisas importantes:
getUpdatesbusca mensagens novas usando long polling;offset = update_id + 1confirma o que já foi processado e evita repetir a mesma atualização;sendMessageenvia o texto de volta para ochat_idrecebido.
Esses métodos são documentados na referência oficial da Bot API. O Telegram mantém as atualizações por tempo limitado e informa que getUpdates não funciona enquanto um webhook estiver configurado para o bot.
4. Execute e faça o primeiro teste
Com a variável de ambiente configurada, rode:
python bot.pyAgora abra o seu bot no Telegram e envie /start. A resposta esperada é “Olá! Eu sou um bot feito em Python.” Depois, envie uma frase qualquer: ela deve voltar no formato “Você disse: …”. O comando /id mostra o chat_id, valor que será útil quando você quiser enviar notificações para uma conversa específica.
Se o programa parecer parado no terminal, isso pode ser normal. A chamada usa um timeout de 50 segundos para esperar atualizações antes de consultar o servidor outra vez. Esse comportamento reduz consultas vazias e é diferente de um erro travado.
Como o código conversa com o Telegram
O endereço-base segue o formato https://api.telegram.org/botSEU_TOKEN/METODO. No exemplo, o Python codifica os parâmetros como formulário HTTPS, recebe um JSON e verifica o campo ok. Depois, o dicionário retornado é usado como dado comum do programa.
O ponto mais importante é o update_id. Cada atualização tem um identificador sequencial; ao pedir a próxima rodada com um número maior, o bot sinaliza que já processou as anteriores. Sem esse controle, uma queda ou uma nova consulta poderia fazer a mesma mensagem ser respondida várias vezes.
Se você já estiver estudando APIs, o fluxo é parecido com o de um cliente HTTP comum. O JSMS também explica como criar uma API REST com Node.js e Express; a diferença aqui é que o servidor do Telegram já está pronto e o seu programa atua como cliente.
Erros comuns e como corrigir
O bot não responde
Confira se o token foi copiado sem espaços, se a variável tem o mesmo nome usado no código e se o bot recebeu uma mensagem sua. Um bot não inicia conversa sozinho. Também verifique se outro programa ou serviço já configurou um webhook, porque isso impede o recebimento por getUpdates.
Aparece “Unauthorized”
O token está inválido, incompleto ou foi revogado. Gere um novo token no BotFather e atualize a variável de ambiente. Não publique o erro junto com o token em fóruns ou repositórios.
A mesma mensagem é respondida várias vezes
Não remova a linha que atualiza o offset. Ela precisa receber o maior update_id processado mais um. Se você interromper o processo antes de enviar a resposta, a atualização poderá aparecer novamente — o que é preferível a perdê-la, mas exige que a lógica real seja idempotente.
O código falha ao importar uma biblioteca
Este exemplo não usa pip nem o pacote python-telegram-bot. Ele depende apenas de módulos da biblioteca padrão, como urllib.request, que a documentação do Python descreve como uma interface para abrir URLs HTTP e HTTPS.
O que melhorar depois do primeiro protótipo
Quando o eco estiver funcionando, você pode separar as funções, validar comandos, registrar logs e salvar dados em um banco. Para uso comercial, acrescente autenticação, limites de requisição, tratamento de mensagens que não sejam texto e uma estratégia de reinício do processo.
O long polling é prático para aprender e para projetos pequenos. Em produção, um webhook costuma ser mais adequado quando você já tem um servidor HTTPS, monitoramento e uma forma segura de validar as requisições recebidas. A escolha depende da infraestrutura, não de uma suposta “mágica” do Telegram.
Perguntas frequentes
É preciso pagar para criar um bot no Telegram?
Para este tutorial, não. Você precisa de uma conta no Telegram, do token criado pelo BotFather e de um computador ou servidor para executar o código. Custos podem aparecer depois, por exemplo, na hospedagem ou em serviços externos conectados ao bot.
Um bot do Telegram pode mandar mensagem para qualquer pessoa?
Não. O usuário precisa iniciar a conversa, adicionar o bot a um grupo ou usar um fluxo permitido pela plataforma. Ter o nome de usuário de alguém não dá ao bot autorização para iniciar uma conversa privada.
Posso trocar o Python por outra linguagem?
Sim. A Bot API usa HTTPS e JSON, então o mesmo fluxo pode ser implementado em JavaScript, Go, Java, PHP ou outra linguagem com suporte a requisições web.
O que fazer se o token do bot vazar?
Revogue o token imediatamente pelo BotFather, gere outro e substitua a variável de ambiente. Depois, procure o segredo em commits, logs e arquivos compartilhados para evitar que ele continue acessível.
Resumo: registrar o bot é rápido; o trabalho de verdade começa quando você decide quais dados ele pode receber, quem pode acioná-lo e como proteger as respostas. Use este eco como laboratório, não como sistema pronto de atendimento.