O guia completo do BotFather

O que é o BotFather no Telegram?

O BotFather é um bot oficial operado pelo Telegram, no username @BotFather, e é a única forma de registrar um novo bot. Você conversa com ele como em qualquer outra conversa: envia comandos, ele faz perguntas, você responde, e ele armazena o resultado.

O BotFather é gratuito. Criar bots não custa nada, não há mensalidade cobrada pelo Telegram, e não há cobrança por mensagem enviada, que é a principal diferença de custo em relação à API do WhatsApp Business. Você pode registrar vários bots a partir de uma única conta do Telegram.

Antes de tocar em Iniciar, verifique se a conta que você abriu tem o selo azul de verificação e o username exato @BotFather. Existem contas falsas com usernames parecidos, e o único propósito delas é coletar os tokens que as pessoas colam ali.

Como se cria um bot com o BotFather?

Você envia /newbot, responde a duas perguntas, e copia o token. O processo todo leva cerca de dois minutos e funciona assim:

1. Abra o @BotFather. Procure por "BotFather" no Telegram, abra a conta verificada, e toque em Iniciar.
2. Envie /newbot. O BotFather responde perguntando o nome do seu novo bot.
3. Envie o nome de exibição. Por exemplo "Sunrise Cafe". É o que os usuários veem no topo da conversa. Espaços, maiúsculas e emojis são permitidos, e você pode alterá-lo depois com /setname.
4. Envie o username. Precisa ter entre 5 e 32 caracteres, usar apenas letras latinas, dígitos e sublinhados, e precisa terminar com a palavra "bot": SunriseCafeBot e sunrise_cafe_bot são ambos válidos, SunriseCafe não é. Usernames são únicos em todo o Telegram, então se o seu já estiver em uso o BotFather simplesmente pede outro.
5. Copie o token. O BotFather te parabeniza e imprime um token de API como 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw. Copie-o em um lugar seguro e trate-o como uma senha.
6. Abra seu bot e toque em Iniciar. Toque no link t.me na resposta do BotFather. O bot existe, mas ainda não vai responder a nada. Isso é esperado.
7. Cole o token em tudo o que vai rodar o bot. Seu próprio código de servidor, ou um construtor no-code onde você define os comandos e respostas. O bot entra no ar no momento em que algo começa a receber atualizações para esse token.

Escolha o username com cuidado. O BotFather tem comandos para mudar nome, foto e descrição de um bot, mas nenhum para mudar seu username, então renomear na prática significa criar um novo bot e apontar seus links para ele.

Se você quiser o caminho completo para iniciantes com capturas de tela do que acontece depois do token, veja como criar um bot do Telegram sem programar.

Quais são todos os comandos do BotFather?

Estes são os comandos que importam para construir e rodar um bot. Enviar /help ao BotFather mostra a lista atual a qualquer momento, e /mybots expõe quase todos eles como botões em vez disso.

O BotFather tem mais alguns comandos que você pode ignorar com tranquilidade no começo, incluindo os comandos de jogos (/newgame, /mygames, /listgames, /editgame, /deletegame), os comandos de ajuste inline (/setinlinegeo, /setinlinefeedback) e /setdomain, que vincula um domínio de site ao Telegram Login Widget.

O que é um token de bot do Telegram e como você o obtém novamente?

O token do bot é a única credencial que permite ao software agir como seu bot, e você pode vê-lo novamente a qualquer momento com /token ou por /mybots e depois Token de API. Ele se parece com isto:

110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

Os dígitos antes dos dois pontos são o ID numérico público do bot. A string depois dos dois pontos é o segredo. Toda chamada da Bot API do Telegram é apenas uma requisição para https://api.telegram.org/bot<token>/methodName, então quem tiver a string completa pode chamar qualquer método como seu bot.

Um token só pode ser usado por um sistema em execução por vez. O Telegram permite apenas uma URL de webhook por bot, e fazer polling de atualizações enquanto um webhook está configurado retorna um erro 409 Conflict. Se você mover um bot de uma plataforma para outra, desconecte a antiga em vez de rodar as duas.

O que acontece se o token do seu bot vazar, e como você o revoga?

Trate o token como uma senha: quem o tiver controla o bot completamente, e a solução é /revoke. Não existe acesso parcial nem modo somente leitura.

Com um token roubado, um atacante pode:

• Ler toda mensagem que os usuários enviarem ao seu bot a partir daquele momento, incluindo qualquer coisa digitada nos seus formulários
• Enviar, editar e excluir mensagens como seu bot para qualquer pessoa que já o tenha iniciado
• Apontar o webhook para o próprio servidor, fazendo seu tráfego ir silenciosamente para ele em vez de para você
• Mudar o menu de comandos, a descrição e o comportamento inline através da Bot API

O que ele não pode fazer também vale a pena saber. O token não dá acesso à sua conta pessoal do Telegram, não pode excluir o bot (isso exige sua conta dentro do BotFather), não pode mandar mensagens a pessoas que nunca iniciaram seu bot, e a Bot API não tem nenhum método para baixar uma lista dos seus usuários, então sua lista de assinantes não é simplesmente exportável.

Para rotacionar um token:

1. Envie /revoke ao BotFather
2. Selecione o bot afetado no teclado que ele mostra
3. O BotFather invalida o token antigo instantaneamente e responde com o novo
4. Cole o novo token em todo lugar onde o antigo estava guardado, já que o bot fica offline até você fazer isso

A prevenção é basicamente um hábito: nunca coloque o token em um lugar público. Não faça commit dele no GitHub, não cole em um grupo ou em um chamado de suporte, e recorte-o de capturas de tela. Repositórios públicos são vasculhados continuamente atrás do padrão de dígitos, dois pontos e letras, e tokens vazados costumam ser explorados em minutos. Mais regras de higiene como essa estão reunidas no nosso post boas práticas para bots do Telegram.

Como você muda nome, descrição, texto sobre ou foto de um bot?

Use /setname, /setdescription, /setabouttext e /setuserpic, ou abra /mybots, escolha o bot e selecione Editar Bot para fazer os quatro a partir de um menu. Cada comando pergunta primeiro qual bot editar, depois pede o novo valor.

Os dois campos de texto são fáceis de confundir. A descrição tem até 512 caracteres e aparece na tela vazia da conversa, acima do botão Iniciar, então é a última coisa que um usuário lê antes de decidir usar seu bot. O texto sobre tem até 120 caracteres e aparece na página de perfil do bot e nas prévias de link quando alguém o compartilha.

As mudanças têm efeito imediato, e nenhuma delas mexe no token ou no username. Se você já tem usuários integrados, renomear é seguro: a conversa deles continua funcionando.

Como você define o menu de comandos que os usuários veem?

Envie /setcommands, escolha seu bot, depois envie a lista inteira em uma mensagem com um comando por linha no formato comando - descrição, sem a barra inicial. Por exemplo:

start - Iniciar o bot e abrir o menu principal
menu - Ver o cardápio atual e preços
book - Reservar uma mesa
hours - Horário de funcionamento e endereço
help - Como usar este bot

As regras do Telegram para essa lista: nomes de comandos usam letras latinas minúsculas, dígitos e sublinhados, têm de 1 a 32 caracteres, e cada descrição tem de 1 a 256 caracteres. Um bot pode ter até 100 comandos no menu. Uma vez salva, a lista aparece quando um usuário digita "/" e atrás do botão Menu ao lado do campo de mensagem.

Uma coisa pega quase todo mundo de surpresa: registrar um comando no BotFather só o torna visível. Não faz ele funcionar. Se você adicionar /hours ao menu mas nada do lado receptor tratar /hours, os usuários tocam nele e recebem silêncio, o que parece pior do que não listá-lo.

O que o BotFather não faz?

O BotFather registra o bot, define seu perfil e entrega um token, e esse é todo o trabalho dele. Ele dá ao seu bot zero comportamento, e é por isso que um bot novinho nunca responde a nada, não importa quanto tempo você espere.

Toda mensagem que um usuário envia ao seu bot vira uma atualização do lado do Telegram. Algo precisa receber essas atualizações, seja por webhook ou por polling, decidir qual deve ser a resposta, e chamar a Bot API para enviá-la. Você tem duas opções realistas para esse algo:

• Escrever e hospedar você mesmo. Um script em Python ou Node, um servidor ou função serverless para rodá-lo, um endpoint HTTPS para o webhook, mais monitoramento e reimplantações para sempre depois disso.
• Usar um construtor no-code. Você cola o token na plataforma, constrói comandos e respostas em um editor visual, e ela cuida de receber atualizações e enviar respostas.

O TeleMinute é do segundo tipo. Você cola o token do BotFather em app.teleminute.com e ganha bots do Telegram ilimitados, comandos e respostas por palavra-chave ilimitados, botões e menus inline, formulários de leads com rastreamento de respostas no app, notificações push quando chega uma nova resposta de formulário, transmissões para todos os usuários do seu bot com agendamento e segmentação, estatísticas detalhadas e relatórios de entrega, e até 4 imagens por comando. Os bots rodam em webhooks do Telegram, então ficam online 24/7 sem servidor para alugar ou manter acordado. Há um bot de teste gratuito de 15 minutos sem cartão exigido, e se quiser comparar o mercado antes, veja nosso comparativo dos melhores criadores de bots do Telegram.

Qualquer que seja o caminho escolhido, duas regras do Telegram valem para todo bot e nenhuma plataforma pode revogá-las. Um bot só pode mandar mensagem para quem o iniciou primeiro, então não há abordagem fria, e o envio em massa é limitado a cerca de 30 mensagens por segundo, então uma transmissão para um público grande entra em fila e leva tempo para terminar.

Como se exclui um bot do Telegram?

Envie /deletebot ao BotFather, escolha o bot, e confirme enviando de volta a frase exata que o BotFather mostra (atualmente "Yes, I am totally sure."). Você pode fazer o mesmo por /mybots e depois Excluir Bot.

A exclusão é permanente. O token para de funcionar, o bot desaparece da sua conta, e o BotFather avisa que não dá para desfazer. Não trate isso como um botão de pausa.

Se você só quer que o bot pare de responder por um tempo, revogue o token com /revoke ou desconecte-o na plataforma que o roda. Ambos levam segundos e são reversíveis.

Principais conclusões

• O BotFather é o bot oficial do Telegram para criar bots, em @BotFather, e é gratuito, sem cobrança por mensagem.
• Crie um bot com /newbot: um nome de exibição, depois um username de 5 a 32 caracteres que precisa terminar em "bot", depois o token.
• O token é uma senha. /token mostra ele de novo, /revoke substitui instantaneamente se vazar.
• O BotFather pode mudar nome, descrição, texto sobre, foto, menu de comandos e configurações de grupo de um bot, mas não seu username.
• O BotFather nunca faz um bot responder. Seu próprio código hospedado ou um construtor como o TeleMinute (US$ 3,99 por semana, US$ 9,99 por mês, ou US$ 49,99 uma única vez) faz essa parte.

Conclusão

O BotFather é pequeno de propósito. É um balcão de registro: emite uma identidade e um token, deixa você refinar o perfil, e fica fora do caminho. Aprenda a dúzia de comandos acima e você nunca mais vai precisar procurá-los.

O trabalho interessante começa depois do token. Decida o que seu bot deve responder, conecte o token a algo capaz de responder, e teste as cinco primeiras perguntas que seus usuários reais vão fazer. Essa é a diferença entre um bot registrado e um bot útil.