Blog MNunes

Como Criar um Chatbot para Telegram com Node.js e Telegraf.js

Escrito por

MNunes

em

,

Os chatbots se tornaram uma ferramenta poderosa para automatizar tarefas, interagir com usuários e fornecer informações de forma instantânea. O Telegram é uma plataforma excelente para desenvolver bots. Neste guia, vamos mergulhar no processo de criação de um chatbot para Telegram utilizando Node.js e a popular biblioteca Telegraf.js. Prepare-se para dar vida ao seu próprio assistente virtual!

O Que Você Vai Aprender:

  • Como registrar seu bot no Telegram usando o BotFather.
  • Como iniciar um projeto Node.js e instalar as dependências necessárias.
  • Como configurar o Telegraf.js para conectar-se à API do Telegram.
  • Como fazer seu bot responder a mensagens de texto.
  • Como implementar comandos específicos para o seu bot.
  • Dicas e ideias para expandir as funcionalidades do seu chatbot.

Passo 1: Conhecendo o BotFather – O Criador de Bots

Antes de escrevermos qualquer linha de código, precisamos registrar nosso bot no Telegram. É aqui que entra o BotFather, um bot oficial do Telegram que gerencia outros bots.

  1. Inicie uma conversa com o BotFather:
    • Abra o Telegram e procure por @BotFather (certifique-se de escolher o oficial, com o selo de verificação).
    • Clique em “Start” ou envie o comando /start.
  2. Crie um novo bot:
    • Envie o comando /newbot.
    • O BotFather pedirá um nome para o seu bot. Este é o nome que será exibido nas conversas. Escolha algo criativo! Por exemplo: Meu Bot Incrível.
    • Em seguida, ele pedirá um nome de usuário (username) para o seu bot. Este nome deve ser único e terminar com “bot”. Por exemplo: meu_bot_incrivel_bot.
  3. Guarde o Token Mágico:
    • Se o nome de usuário estiver disponível, o BotFather parabenizará você e fornecerá um token de acesso HTTP API. Este token é super importante e secreto! Ele é a chave que permite que seu código Node.js controle seu bot. Guarde-o em um local seguro.

Passo 2: Preparando o Ambiente de Desenvolvimento Node.js

Com o token em mãos, é hora de configurar nosso projeto Node.js.

  1. Crie uma pasta para o projeto: Abra seu terminal ou prompt de comando e crie uma nova pasta para o seu bot. Navegue até ela:mkdir meu-chatbot-telegram cd meu-chatbot-telegram
  2. Inicie o projeto Node.js: Execute o comando abaixo para criar um arquivo package.json. Este arquivo gerenciará as dependências do seu projeto.npm init -y
    O -y aceita as configurações padrão, o que é suficiente para começarmos.
  3. Instale o Telegraf.js: Agora, vamos instalar a biblioteca Telegraf.js, que facilitará muito a nossa interação com a API do Telegram.npm install telegraf

Passo 3: Configurando o Telegraf.js e Conectando seu Bot

Chegou a hora de escrever um pouco de código! Crie um arquivo chamado bot.js (ou o nome que preferir, como index.js) na pasta do seu projeto e adicione o seguinte código:

// Importa a classe Telegraf da biblioteca telegraf
const { Telegraf } = require('telegraf');

// Substitua 'SEU_TOKEN_AQUI' pelo token que você recebeu do BotFather
const BOT_TOKEN = 'SEU_TOKEN_AQUI';

// Verifica se o token foi fornecido
if (!BOT_TOKEN) {
  console.error('Erro: O token do bot não foi fornecido! Por favor, adicione seu token no arquivo bot.js');
  process.exit(1); // Encerra o processo se o token estiver ausente
}

// Cria uma nova instância do bot Telegraf
const bot = new Telegraf(BOT_TOKEN);

// Middleware para logar cada requisição recebida (opcional, mas útil para debug)
bot.use(async (ctx, next) => {
  const start = new Date();
  await next(); // Chama o próximo middleware ou handler
  const ms = new Date() - start;
  console.log('Resposta para %s em %sms', ctx.updateType, ms);
});

// Inicia o bot e o faz escutar por atualizações
bot.launch(() => {
  console.log('Bot iniciado com sucesso!');
  console.log('Envie mensagens ou comandos para interagir.');
});

// Tratamento de erros para garantir que o bot não pare inesperadamente
bot.catch((err, ctx) => {
  console.error(`Ooops, ocorreu um erro para ${ctx.updateType}`, err);
  // Você pode adicionar aqui uma lógica para notificar o usuário sobre o erro, se desejar.
  // ctx.reply('Desculpe, algo deu errado. Tente novamente mais tarde.');
});

// Permite que o bot pare de forma graciosa ao receber sinais de interrupção (Ctrl+C)
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));

console.log('Iniciando o bot...');

Explicação do Código:

  • const { Telegraf } = require('telegraf');: Importamos a classe Telegraf.
  • const BOT_TOKEN = 'SEU_TOKEN_AQUI';: Lembre-se de substituir 'SEU_TOKEN_AQUI' pelo token real do seu bot. É uma boa prática armazenar tokens e chaves secretas em variáveis de ambiente para maior segurança, mas para este exemplo inicial, vamos mantê-lo simples.
  • const bot = new Telegraf(BOT_TOKEN);: Criamos uma instância do nosso bot.
  • bot.use(...): Este é um exemplo de middleware. Middlewares no Telegraf processam as atualizações (mensagens, comandos, etc.) antes que cheguem aos seus handlers específicos. Este aqui apenas registra o tempo de resposta.
  • bot.launch(): Inicia o bot. Ele começará a “ouvir” por mensagens e outras interações no Telegram.
  • bot.catch(...): Captura erros que podem ocorrer durante o processamento das atualizações, evitando que o bot pare de funcionar.
  • process.once(...): Garante que o bot seja interrompido corretamente quando você pressionar Ctrl+C no terminal.

Para executar seu bot: Salve o arquivo bot.js e, no terminal, dentro da pasta do projeto, execute:

node bot.js

Se tudo estiver correto, você verá a mensagem “Iniciando o bot…” e depois “Bot iniciado com sucesso!”. Agora, seu bot está online, mas ainda não faz nada muito interessante. Vamos mudar isso!

Passo 4: Respondendo a Mensagens de Texto

Queremos que nosso bot responda quando alguém envia uma mensagem de texto para ele. O Telegraf torna isso muito fácil com o método on().

Adicione o seguinte código ao seu arquivo bot.js, antes da linha bot.launch():

// ... (código anterior) ...

// Handler para qualquer mensagem de texto recebida
bot.on('text', (ctx) => {
  // ctx (context) contém informações sobre a mensagem recebida
  const textoRecebido = ctx.message.text;
  console.log(`Texto recebido: ${textoRecebido}`);

  // Responde ao usuário com uma mensagem ecoando o que foi recebido
  // ctx.reply() envia uma mensagem de volta para o mesmo chat
  ctx.reply(`Você disse: "${textoRecebido}"`);

  // Você pode adicionar lógicas mais complexas aqui.
  // Por exemplo, verificar o conteúdo da mensagem:
  if (textoRecebido.toLowerCase().includes('olá') || textoRecebido.toLowerCase().includes('oi')) {
    ctx.reply('Olá! Como posso te ajudar hoje? 😊');
  } else if (textoRecebido.toLowerCase() === 'qual o seu nome?') {
    // botInfo é preenchido automaticamente pelo Telegraf com informações do bot
    ctx.reply(`Meu nome é ${ctx.botInfo.first_name}!`);
  }
});

// ... (bot.launch() e código posterior) ...

Explicação:

  • bot.on('text', (ctx) => { ... });: Este handler é acionado sempre que o bot recebe uma mensagem do tipo text.
  • ctx: O objeto de contexto (ctx) é fundamental no Telegraf. Ele contém todas as informações sobre a atualização recebida (quem enviou, qual a mensagem, o chat, etc.) e métodos para responder (ctx.reply(), ctx.sendMessage(), etc.).
  • ctx.message.text: Acessa o conteúdo da mensagem de texto.
  • ctx.reply(...): Envia uma resposta de volta para o chat de onde a mensagem original veio.
  • No exemplo, adicionamos uma lógica simples para responder de forma diferente a saudações ou perguntas sobre o nome do bot.

Teste: Salve o arquivo bot.js e reinicie seu bot (pare o processo anterior com Ctrl+C e execute node bot.js novamente). Agora, vá até o Telegram, encontre seu bot e envie algumas mensagens de texto para ele. Você deverá ver as respostas que configuramos!

Passo 5: Criando Comandos Personalizados

Comandos são uma forma comum de interagir com bots no Telegram. Eles geralmente começam com uma barra / (por exemplo, /start, /help). O Telegraf oferece o método command() para lidar com eles.

Vamos criar um comando /ajuda que informa ao usuário o que o bot pode fazer. Adicione este código ao seu bot.js, também antes de bot.launch():

// ... (código anterior, incluindo o handler bot.on('text', ...)) ...

// Handler para o comando /start
// O comando /start é frequentemente usado para uma mensagem de boas-vindas.
bot.command('start', (ctx) => {
  const nomeUsuario = ctx.message.from.first_name;
  ctx.replyWithMarkdown(
`👋 Olá, **${nomeUsuario}**! Bem-vindo(a) ao nosso bot de exemplo.

Eu sou um bot simples construído com Telegraf.js.

Você pode tentar:
➡️ Enviar qualquer mensagem de texto para mim.
➡️ Usar o comando /ajuda para ver esta mensagem novamente.
➡️ Usar o comando /tempo para uma (simulada) previsão do tempo.

Divirta-se explorando! ✨`
  );
});

// Handler para o comando /ajuda
bot.command('ajuda', (ctx) => {
  ctx.replyWithHTML(
`<b>Central de Ajuda do Bot</b> 🤖

Aqui estão algumas coisas que posso fazer:
<ul>
  <li>Responder às suas mensagens de texto.</li>
  <li>Mostrar esta mensagem de ajuda com o comando /ajuda.</li>
  <li>Simular uma previsão do tempo com /tempo.</li>
</ul>

<i>Fique à vontade para experimentar!</i>`
  );
});

// Handler para um comando fictício /tempo
bot.command('tempo', (ctx) => {
  // Em um bot real, você poderia integrar com uma API de previsão do tempo.
  const cidades = ['São Paulo', 'Rio de Janeiro', 'Belo Horizonte', 'Curitiba', 'Salvador'];
  const condicoes = ['Ensolarado ☀️', 'Nublado 🌥️', 'Chuvoso 🌧️', 'Tempestade ⛈️', 'Neve ❄️ (improvável no Brasil!)'];
  const cidadeAleatoria = cidades[Math.floor(Math.random() * cidades.length)];
  const condicaoAleatoria = condicoes[Math.floor(Math.random() * condicoes.length)];

  ctx.reply(`Previsão do tempo para ${cidadeAleatoria}: ${condicaoAleatoria}`);
});

// ... (bot.launch() e código posterior) ...

Explicação:

  • bot.command('nome_do_comando', (ctx) => { ... });: Define um handler para um comando específico. Não inclua a / no nome do comando aqui.
  • No comando /start, usamos ctx.message.from.first_name para pegar o primeiro nome do usuário e personalizar a saudação. Usamos ctx.replyWithMarkdown() para formatar a mensagem com Markdown (negrito, etc.).
  • No comando /ajuda, usamos ctx.replyWithHTML() para demonstrar que também é possível enviar mensagens formatadas com HTML.
  • O comando /tempo é um exemplo simples que retorna uma “previsão” aleatória.

Teste: Salve, reinicie o bot e experimente enviar os comandos /start, /ajuda e /tempo para o seu bot no Telegram.

Passo 6: Dicas para Evoluir seu Projeto

Você construiu a base do seu chatbot! Agora, o céu é o limite. Aqui estão algumas ideias e dicas para levar seu projeto para o próximo nível:

  1. Integração com APIs Externas:
    • Conecte seu bot a APIs de notícias, previsão do tempo, tradução, cotação de moedas, Wikipédia, etc.
    • Use bibliotecas como axios ou node-fetch para fazer requisições HTTP.
  2. Persistência de Dados:
    • Para lembrar informações sobre usuários ou conversas, você precisará de um banco de dados.
    • Opções populares incluem MongoDB (com Mongoose), PostgreSQL (com Sequelize ou TypeORM) ou até mesmo bancos de dados NoSQL mais simples como Redis.
    • Guarde preferências do usuário, histórico de conversas, etc.
  3. Processamento de Linguagem Natural (PLN):
    • Para interações mais inteligentes e menos dependentes de comandos exatos, explore bibliotecas de PLN.
    • Opções como Dialogflow (Google), Wit.ai (Facebook) ou RASA (open-source) podem ajudar seu bot a entender a intenção do usuário.
  4. Teclados Personalizados e Botões Inline:
    • O Telegram permite criar teclados personalizados que aparecem no lugar do teclado padrão e botões inline que aparecem diretamente nas mensagens do bot.Isso melhora muito a usabilidade. Pesquise por Markup.keyboard() e Markup.inlineKeyboard() na documentação do Telegraf.
// Exemplo de teclado personalizado
bot.command('menu', (ctx) => {
  ctx.reply('Escolha uma opção:', Markup.keyboard([
    ['Opção 1', 'Opção 2'], // Linha 1
    ['Opção 3'],             // Linha 2
    ['/fecharmenu']          // Comando para fechar o teclado
  ]).resize()); // .resize() ajusta o tamanho do teclado
});

bot.hears('Opção 1', ctx => ctx.reply('Você escolheu a Opção 1!'));
bot.command('fecharmenu', ctx => ctx.reply('Menu fechado.', Markup.removeKeyboard()));

// Exemplo de botões inline
bot.command('inline', (ctx) => {
  ctx.reply('Clique em um botão:', Markup.inlineKeyboard([
    Markup.button.callback('Botão A', 'acao_A'),
    Markup.button.callback('Botão B', 'acao_B')
  ]));
});

// Handlers para as ações dos botões inline
bot.action('acao_A', ctx => {
  ctx.answerCbQuery('Você clicou no Botão A!'); // Resposta para o clique (feedback visual)
  ctx.editMessageText('Você clicou no Botão A. A mensagem foi editada!'); // Edita a mensagem original
});
bot.action('acao_B', ctx => {
  ctx.answerCbQuery('Você clicou no Botão B!');
  ctx.reply('Você clicou no Botão B! Uma nova mensagem foi enviada.');
});
  1. Webhook em vez de Polling (para produção):
    • Por padrão (bot.launch()), o Telegraf usa “long polling”, onde seu servidor pergunta repetidamente ao Telegram se há novas mensagens.
    • Para produção, é mais eficiente usar webhooks. Com webhooks, o Telegram envia ativamente as atualizações para uma URL que você especifica no seu servidor. Isso requer um servidor com HTTPS.
    • Consulte a documentação do Telegraf sobre bot.telegram.setWebhook(URL_DO_SEU_WEBHOOK) e como configurar um servidor web (por exemplo, com Express.js) para receber essas atualizações.
  2. Organização do Código:
    • À medida que seu bot cresce, divida seu código em múltiplos arquivos (módulos) para melhor organização.
    • Crie pastas para comandos, handlers, serviços, etc.
  3. Variáveis de Ambiente:
    • NUNCA coloque seu token de bot diretamente no código em um repositório público. Use variáveis de ambiente (por exemplo, com o pacote dotenv) para armazenar informações sensíveis.
    • Crie um arquivo .env (e adicione-o ao seu .gitignore):BOT_TOKEN=SEU_TOKEN_AQUI_REAL
    • No seu bot.js:require('dotenv').config(); const BOT_TOKEN = process.env.BOT_TOKEN;
  4. Tratamento de Erros Avançado:
    • Implemente um sistema de logging mais robusto (por exemplo, com Winston ou Pino).
    • Notifique administradores sobre erros críticos.

Conclusão

Parabéns! Você aprendeu os fundamentos para criar um chatbot para Telegram usando Node.js e Telegraf.js. Desde o registro no BotFather, passando pela configuração do projeto, até a implementação de respostas a textos e comandos, você agora tem uma base sólida.

O mundo dos chatbots é vasto e cheio de possibilidades. Continue explorando, experimentando com as dicas de evolução e, o mais importante, divirta-se criando interações úteis e criativas para seus usuários!

Se tiver dúvidas ou quiser compartilhar suas criações, deixe um comentário abaixo!

Próximos Passos Sugeridos:

  • Experimente adicionar um novo comando ao seu bot.
  • Tente integrar uma API externa simples (como uma API de piadas ou fatos aleatórios).
  • Explore os teclados personalizados do Telegraf.

Links úteis

Repsoitório desse projeto: https://github.com/marcosnunesmbs/telegram-bot-tutorial
Botfather: https://t.me/botfather

Mais posts