Você pode criar um bot funcional no Telegram sem montar um sistema enorme: basta registrar a conta automatizada no BotFather, guardar o token e conectar um pequeno programa à Bot API.
Neste tutorial, vamos fazer o caminho mais simples com Python e long polling. O bot receberá mensagens, responderá ao comando /start e repetirá outros textos. É uma base pequena, mas já serve para entender a mecânica antes de integrar atendimento, alertas ou automações.
O que você precisa antes de começar
- uma conta no Telegram;
- Python 3 instalado no computador;
- um editor de texto;
- um terminal para executar o programa;
- um lugar seguro para guardar o token do bot.
O token funciona como uma senha da sua automação. Quem tiver esse código pode chamar a API em nome do bot. Por isso, não coloque o token em um repositório público, em uma captura de tela ou diretamente no código que será compartilhado.
Como criar o bot no BotFather
O BotFather é o bot oficial usado para registrar e administrar outros bots. A própria documentação do Telegram recomenda começar por ele.
- Abra o Telegram e procure por @BotFather. Confira o selo e o nome de usuário antes de iniciar.
- Toque em Start ou envie
/start. - Envie o comando
/newbot. - Digite um nome visível, como
Atendimento da Loja. - Escolha um nome de usuário único. Ele deve terminar em
bot, por exemploatendimento_loja_bot. - Copie o token mostrado pelo BotFather e guarde-o fora do código.
Se o nome de usuário já estiver ocupado, o BotFather pedirá outra opção. O nome visível pode ter espaços; o username usado no link do bot é mais restrito.
Depois de criar a conta, abra o endereço do bot ou procure pelo username e toque em Start. Esse passo é importante: em uma conversa privada, o bot não pode iniciar contato com alguém que nunca falou com ele.
Como preparar o Python
Crie uma pasta para o projeto e defina o token como variável de ambiente. Assim, o segredo fica separado do arquivo do programa.
# Linux e macOS
export TELEGRAM_BOT_TOKEN='cole_o_token_apenas_no_seu_terminal'
# Windows PowerShell
$env:TELEGRAM_BOT_TOKEN = 'cole_o_token_apenas_no_seu_terminal'O valor acima é apenas um exemplo. Não publique o token real no GitHub, em um tutorial ou em um grupo de mensagens. Se ele escapar, revogue-o pelo BotFather e gere outro.
Como criar um bot que responde mensagens
Salve o arquivo abaixo como bot.py. O exemplo usa somente a biblioteca padrão do Python, então não exige instalar um pacote externo.
import json
import os
import time
import urllib.parse
import urllib.request
from urllib.error import HTTPError, URLError
TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/"
def call(method, data=None):
encoded = urllib.parse.urlencode(data or {}).encode("utf-8")
request = urllib.request.Request(
API + method,
data=encoded,
headers={"Content-Type": "application/x-www-form-urlencoded"},
)
with urllib.request.urlopen(request, timeout=40) as response:
payload = json.load(response)
if not payload.get("ok"):
raise RuntimeError(payload.get("description", "Erro na Bot API"))
return payload["result"]
def main():
me = call("getMe")
print(f"Bot conectado: @{me['username']}")
offset = 0
while True:
try:
updates = call(
"getUpdates",
{
"timeout": 30,
"offset": offset,
"allowed_updates": json.dumps(["message"]),
},
)
for update in updates:
offset = update["update_id"] + 1
message = update.get("message", {})
text = message.get("text")
chat_id = message.get("chat", {}).get("id")
if not text or chat_id is None:
continue
if text == "/start":
reply = "Olá! Eu estou funcionando. Envie uma mensagem."
elif text == "/help":
reply = "Comandos: /start e /help. Também posso repetir uma mensagem."
else:
reply = f"Você escreveu: {text}"
call("sendMessage", {"chat_id": chat_id, "text": reply})
except (HTTPError, URLError, TimeoutError) as error:
print(f"Falha temporária: {error}")
time.sleep(5)
if __name__ == "__main__":
main()Execute no terminal:
python bot.pySe o token estiver correto, o terminal exibirá o username do bot e ficará aguardando atualizações. Agora abra o chat do bot no Telegram, envie /start e depois mande uma frase qualquer. A resposta deve aparecer no mesmo chat.
O que esse código está fazendo?
A Bot API é uma interface HTTP. Isso significa que o programa envia requisições para URLs e recebe respostas em JSON, um formato de texto organizado que o Python consegue ler.
getMeconfirma que o token identifica um bot válido;getUpdatesbusca mensagens novas usando long polling;offsetavança o marcador para que a mesma atualização não seja processada de novo;sendMessageenvia a resposta para ochat_idrecebido;allowed_updateslimita o exemplo a atualizações do tipo mensagem.
Long polling é uma técnica simples: o programa faz uma requisição e o Telegram segura a resposta por alguns segundos quando ainda não há novidade. Quando chega uma mensagem, a resposta volta e o loop continua. Para um protótipo e um bot pequeno, esse caminho é mais fácil de entender do que começar com um servidor público.
O Telegram também oferece webhooks. Nesse modelo, em vez de perguntar ao Telegram se há novidades, você publica uma URL HTTPS e a plataforma envia cada atualização para ela. Os dois modos são mutuamente exclusivos: enquanto um webhook estiver configurado, getUpdates não funciona.
Como testar e corrigir os erros mais comuns
O bot não responde
Confira se você abriu o chat correto e tocou em Start. Em conversa privada, o usuário precisa falar primeiro com o bot. Também verifique se a variável de ambiente foi criada no mesmo terminal em que você executou python bot.py.
Aparece erro de token
Gere um novo token pelo BotFather se você copiou algum caractere errado ou se o segredo foi exposto. Não tente corrigir colocando o token diretamente no código compartilhado.
A mensagem chega repetida
O programa precisa atualizar o offset com o update_id processado mais um. O exemplo faz isso antes de enviar a resposta. Se você interromper o programa antes de confirmar uma atualização, ela pode voltar na próxima execução.
O programa para depois de um tempo
Verifique a mensagem exibida no terminal. O exemplo tenta novamente em falhas temporárias de rede, mas não substitui logs, monitoramento e reinicialização automática. Para deixar um bot online o tempo todo, ele precisa rodar em um computador ligado ou em um servidor.
Como evoluir esse primeiro bot
Depois do eco básico, você pode separar comandos, criar botões, consultar uma planilha, chamar uma API ou encaminhar conversas para uma equipe. O limite aparece quando o programa começa a depender de memória, banco de dados, autenticação e regras de negócio.
Se a sua ideia é conectar o Telegram a outros serviços sem escrever toda a infraestrutura, um webhook pode ser o próximo passo. O JSMS também explica como criar um webhook no n8n e testar com curl; a lógica de receber um evento e encaminhá-lo para uma automação é parecida.
Para atendimento real, não trate esse exemplo como produto pronto. Adicione controle de acesso, armazenamento seguro, tratamento para mensagens que não sejam texto, limites de requisição, logs sem tokens e uma estratégia de backup. Um bot que responde “olá” é um bom começo; um bot responsável precisa saber também quando não responder.
Perguntas frequentes
Posso criar um bot no Telegram sem programar?
O registro pelo BotFather é simples, mas um bot funcional precisa de código ou de uma plataforma que execute essa lógica por você. A FAQ oficial do Telegram indica que não há um caminho pronto para criar um bot funcional sem desenvolvimento.
O bot pode mandar mensagem primeiro para uma pessoa?
Em uma conversa privada, não. A pessoa precisa abrir o chat e enviar uma mensagem ao bot antes que ele possa responder.
Qual é a diferença entre getUpdates e webhook?
getUpdates usa long polling para o seu programa buscar novidades. O webhook envia as novidades para uma URL HTTPS. São modos alternativos: um webhook ativo impede o uso de getUpdates.
O que faço se o token do bot vazar?
Revogue o token no BotFather e gere outro imediatamente. Depois, remova o segredo de arquivos, logs e repositórios onde ele apareceu.