Documentação

Criando seu robô no Telegram

Seu agente mora dentro de um robô do Telegram que é seu — não nosso. Você cria em uns dois minutos, de graça, e ele continua seu mesmo se um dia você sair da plataforma. Esta página é a versão longa do passo 2 do assistente de criação.

O que é o BotFather

O BotFather é o robô do próprio Telegram para criar robôs. É oficial, feito pelo Telegram, e é o único caminho para ter um bot. Você conversa com ele como conversa com uma pessoa: manda mensagem, ele responde.

Confira o selo azul

Procurar por “botfather” no Telegram traz imitadores. O verdadeiro é o @BotFather com o selo azul de verificado ao lado do nome. Nunca cole um token em nenhuma outra conversa.

Criando o robô

1
Abra o Telegram e procure por @BotFather. Abra a conversa e toque em Começar.
2
Envie /newbot.
3
Ele pede um nome. É o nome que aparece no topo da conversa — pode ter espaço e acento. Ex.: Sofia.
4
Ele pede um nome de usuário. É o @arroba, e precisa terminar em bot. Ex.: sofia_casa_bot.
5
O BotFather responde com um token comprido. Toque nele para copiar, volte ao assistente e cole. A gente confere na hora.

As três coisas que ele pede

O quê	Exemplo	Regras
Nome	`Sofia`	Texto livre. Aparece no topo da conversa. Dá para mudar depois.
Nome de usuário	`sofia_casa_bot`	Único no Telegram inteiro, de 5 a 32 caracteres, só letras, números e underline, e tem que terminar em bot. É definitivo.
Token	`123456789:AAEhBO…`	Gerado pelo BotFather. É a senha do seu robô — trate como uma.

Se aparecer “Sorry, this username is already taken”, alguém chegou antes — o arroba precisa ser único no mundo todo. Coloque algo seu: sobrenome, cidade, um número.

Sobre o token

O token é o que permite a um programa responder mensagens no lugar do seu robô. Quem tiver ele nas mãos consegue ler e escrever em nome do robô, então:

Nunca mande em grupo, em print de tela ou por e-mail.
A gente guarda cifrado, e ele só é usado pelo seu próprio agente.
Se achar que vazou, mande /revoke para o BotFather, escolha o robô e ele te entrega um token novo. O antigo morre na hora — aí é só colar o novo na página do seu agente.
Perdeu o token? Mande /token para o BotFather e escolha o robô.

Um robô, um agente

Um token só pode ser usado por um programa de cada vez. Se o mesmo robô estiver ligado a dois agentes — ou a alguma outra automação que você montou antes — os dois começam a perder mensagens. Crie um robô separado para cada agente.

Acabamentos opcionais

Puramente estético, tudo enviando estes comandos ao BotFather:

/setuserpic — a foto de perfil.
/setdescription — o texto que aparece na tela vazia da conversa, antes de a pessoa tocar em Começar.
/setabouttext — a frase curta no perfil do robô.
/setname — muda o nome de exibição (o @arroba não muda nunca).

Quando dá errado

O que aparece	O que significa
Invalid username	Precisa terminar em bot e só aceita letras, números e underline. Sem hífen, sem espaço, sem acento.
Sorry, this username is already taken	Os arrobas são únicos no Telegram inteiro. Tente uma variação.
A gente recusa o token	Quase sempre é acidente na cópia: um espaço a mais, uma quebra de linha, ou a mensagem errada copiada. Copie de novo tocando direto no token, dentro da conversa do BotFather.
O robô não responde	Duas causas comuns: você ainda não criou o agente, ou nunca mandou /start para o robô. As duas estão cobertas no assistente de criação.