Como criar um bot no Telegram com IA usando Gemini: tutorial simples para iniciantes

Hoje é possível criar um assistente simples de inteligência artificial usando ferramentas acessíveis, gratuitas para começar e relativamente fáceis de configurar. Com uma conta no Telegram, o BotFather, Python e a Gemini API, você consegue montar um bot que recebe uma pergunta e responde com IA dentro do próprio Telegram.

Este tutorial foi pensado para iniciantes. A ideia não é criar um sistema complexo logo de cara, mas mostrar o caminho básico para você entender como as peças se conectam: o usuário fala com o bot, o Python recebe a mensagem, envia para o Gemini e devolve a resposta para o chat.

O resultado será um primeiro projeto funcional de bot Telegram com IA, que depois pode evoluir para automações mais úteis, como resumo de notícias, alerta de promoções, atendimento básico, integração com WordPress ou ferramentas pessoais de estudo.

O que será criado neste tutorial

Você vai criar um bot simples que funciona em quatro etapas:

• recebe mensagens de texto pelo Telegram;
• envia a pergunta para a Gemini API;
• recebe a resposta gerada pela inteligência artificial;
• devolve essa resposta para o usuário no próprio Telegram.

Esse tipo de projeto é ótimo para aprender automação com IA, porque mistura uma interface conhecida, o Telegram, com um modelo de linguagem acessado por API. Você não precisa criar aplicativo, tela, login ou banco de dados nesta primeira versão.

Ferramentas necessárias

Antes de começar, separe estas ferramentas:

• Conta no Telegram;
• BotFather, que é o bot oficial para criar bots no Telegram;
• Conta Google;
• Acesso ao Google AI Studio;
• Python instalado no computador;
• Editor de código, como VS Code;
• Biblioteca python-telegram-bot;
• SDK oficial atual do Gemini para Python, o pacote google-genai;
• Biblioteca python-dotenv para carregar variáveis do arquivo .env.

Nos documentos atuais do Google, o pacote recomendado para novos projetos em Python é o google-genai. O pacote antigo google-generativeai ainda aparece em muitos tutoriais, mas aqui vamos usar o SDK mais novo.

Criando o bot no Telegram

O primeiro passo é criar o bot dentro do próprio Telegram. Para isso, você vai conversar com o BotFather, que é a ferramenta oficial do Telegram para registrar novos bots.

• Abra o Telegram no celular ou no computador.
• Procure por BotFather.
• Abra a conversa com o bot verificado.
• Digite o comando /newbot.
• Escolha um nome para o bot, por exemplo: Meu Assistente IA.
• Escolha um usuário para o bot, que precisa terminar com bot, como meu_assistente_ia_bot.
• Copie o token gerado pelo BotFather.

Aviso importante: nunca publique o token do bot em prints, GitHub, fóruns ou arquivos públicos. Quem tiver esse token pode controlar o seu bot.

Criando a chave da API Gemini

Agora você precisa da chave da Gemini API. Essa chave permite que o seu código Python envie perguntas para o modelo Gemini usando sua conta.

• Acesse o Google AI Studio.
• Faça login com sua conta Google.
• Crie uma nova API Key.
• Copie a chave gerada.
• Guarde em um local seguro.

Assim como o token do Telegram, a chave do Gemini nunca deve ficar visível em código público. Não cole essa chave em posts, prints, repositórios abertos ou mensagens compartilhadas.

Criando a estrutura do projeto

Crie uma pasta para o projeto. Dentro dela, teremos três arquivos principais:

meu-bot-ia/
├── bot.py
├── .env
└── requirements.txt

O arquivo bot.py terá o código principal. O arquivo .env guardará as chaves secretas. O requirements.txt listará as bibliotecas necessárias para instalar o projeto em outro computador ou servidor.

Instalando as dependências

Abra o terminal dentro da pasta do projeto e instale as bibliotecas:

pip install python-telegram-bot python-dotenv google-genai

Depois, crie o arquivo requirements.txt com o seguinte conteúdo:

python-telegram-bot
python-dotenv
google-genai

Se você quiser instalar tudo pelo arquivo depois, use:

pip install -r requirements.txt

Criando o arquivo .env

Na raiz do projeto, crie um arquivo chamado .env. Ele deve guardar o token do Telegram e a chave do Gemini:

TELEGRAM_TOKEN=coloque_aqui_o_token_do_telegram
GEMINI_API_KEY=coloque_aqui_a_chave_do_gemini

Não use aspas se não precisar. Também não coloque espaços antes ou depois do sinal de igual. E, principalmente, não envie esse arquivo para o GitHub.

Para evitar acidentes, crie também um arquivo .gitignore com esta linha:

.env

Criando o código do bot

Agora vem a parte principal. O código abaixo carrega as variáveis do .env, conecta ao Telegram, recebe mensagens de texto, envia o conteúdo para o Gemini e responde ao usuário.

Crie o arquivo bot.py e cole o código:

import asyncio
import logging
import os

from dotenv import load_dotenv
from google import genai
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes, MessageHandler, filters

load_dotenv()

TELEGRAM_TOKEN = os.getenv("TELEGRAM_TOKEN")
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

if not TELEGRAM_TOKEN:
    raise RuntimeError("TELEGRAM_TOKEN não foi encontrado no arquivo .env")

if not GEMINI_API_KEY:
    raise RuntimeError("GEMINI_API_KEY não foi encontrado no arquivo .env")

logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    level=logging.INFO,
)

client = genai.Client(api_key=GEMINI_API_KEY)


def gerar_resposta_com_gemini(pergunta: str) -> str:
    """Envia a mensagem do usuário para o Gemini e retorna o texto da resposta."""
    resposta = client.models.generate_content(
        model="gemini-2.5-flash",
        contents=pergunta,
    )

    return resposta.text or "Não consegui gerar uma resposta agora."


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text(
        "Olá! Eu sou um bot com IA usando Gemini. Envie uma pergunta para começar."
    )


async def responder(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    pergunta = update.message.text

    try:
        await update.message.reply_text("Pensando...")

        resposta = await asyncio.to_thread(gerar_resposta_com_gemini, pergunta)

        # O Telegram tem limite de tamanho por mensagem. Este corte evita erro em respostas longas.
        await update.message.reply_text(resposta[:4000])

    except Exception:
        logging.exception("Erro ao gerar resposta")
        await update.message.reply_text(
            "Desculpe, aconteceu um erro ao consultar a IA. Tente novamente em instantes."
        )


def main() -> None:
    app = ApplicationBuilder().token(TELEGRAM_TOKEN).build()

    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, responder))

    print("Bot iniciado. Pressione Ctrl+C para parar.")
    app.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

O que esse código faz?

A função load_dotenv() carrega as chaves do arquivo .env. Depois, o código cria um cliente do Gemini com genai.Client e monta a aplicação do Telegram com ApplicationBuilder.

Quando o usuário envia /start, o bot responde com uma mensagem inicial. Quando o usuário envia qualquer texto comum, a função responder pega a pergunta, chama o Gemini e devolve a resposta no Telegram.

O uso de asyncio.to_thread ajuda a não travar o processamento assíncrono do bot enquanto a chamada para a API está acontecendo.

Testando o bot

Com tudo pronto, execute o bot no terminal:

python bot.py

Se estiver tudo correto, o terminal mostrará que o bot foi iniciado. Agora abra o Telegram, procure pelo usuário do bot que você criou no BotFather e envie o comando:

/start

Depois, envie uma pergunta simples, como:

Explique o que é inteligência artificial em linguagem simples.

O bot deve responder no próprio chat. Se aparecer erro, confira três pontos: se o token do Telegram está correto, se a chave do Gemini está correta e se todas as bibliotecas foram instaladas.

Melhorias possíveis

Depois que a versão básica estiver funcionando, você pode evoluir o projeto de várias formas:

• adicionar memória de conversa para o bot lembrar o contexto;
• limitar usuários autorizados pelo ID do Telegram;
• salvar histórico em banco de dados;
• conectar o bot com WordPress para criar rascunhos ou consultar posts;
• criar resumo automático de notícias;
• criar alerta de promoções;
• hospedar em um servidor próprio, VPS ou ZimaOS.

Essas melhorias transformam o projeto em algo mais próximo de um assistente pessoal ou ferramenta de automação real.

Cuidados de segurança

Mesmo sendo um projeto simples, segurança importa. Tokens e chaves de API funcionam como senhas. Se alguém tiver acesso a eles, pode usar seu bot ou consumir sua cota da API.

• Não exponha tokens em prints, vídeos ou repositórios públicos.
• Não envie o arquivo .env para GitHub.
• Use .gitignore para bloquear arquivos sensíveis.
• Monitore o consumo da Gemini API.
• Limite o uso do bot se ele for ficar online o tempo todo.
• Evite deixar o bot aberto para qualquer pessoa sem controle.

Se uma chave vazar, revogue a chave antiga e gere outra. Não tente “esconder” uma chave que já apareceu publicamente, porque ela deve ser considerada comprometida.

Conclusão

Criar um bot no Telegram com IA usando Gemini é um ótimo primeiro passo para entender automação com inteligência artificial. Com poucas ferramentas, você monta um assistente capaz de receber mensagens, conversar com um modelo de IA e responder direto no Telegram.

A partir daqui, você pode evoluir o projeto para tarefas mais avançadas: organizar estudos, resumir documentos, acompanhar notícias, gerar ideias de conteúdo, monitorar promoções ou integrar com outros sistemas.

Você usaria um bot de IA no Telegram para estudar, trabalhar ou automatizar tarefas do dia a dia?

Fontes e documentação

• Google AI for Developers – Gemini API quickstart
• Google AI Studio – criar API Key
• python-telegram-bot – documentação oficial
• Telegram Bots – documentação oficial