Como criar um bot no Telegram grátis: do BotFather à primeira mensagem

Atualizado em: 29 de outubro de 2026 · 7 min de leitura

Para criar bot no Telegram, abra o @BotFather, envie /newbot e escolha um nome e um username terminado em bot. Em menos de um minuto você recebe o token de acesso à Bot API — e é tudo grátis. Neste passo a passo você cria o bot, testa o token com getMe e envia a primeira mensagem com curl e Python.

O que você precisa

• Uma conta no Telegram (celular ou desktop).
• Um terminal com curl — ou apenas o navegador.
• Para programar: Python 3 com a biblioteca requests (ou Node.js).

Não é preciso ter servidor para começar: com long polling, o bot roda no seu próprio computador.

Passo 1: criar o bot no @BotFather com /newbot

1. No Telegram, procure @BotFather (o oficial tem o selo de verificado) e toque em Iniciar.
2. Envie /newbot.
3. Digite o nome de exibição, por exemplo Loja do João. Ele pode ter espaços e ser alterado depois com /setname.
4. Digite o username: de 5 a 32 caracteres, só letras latinas, números e underline, terminando em bot — como loja_joao_bot ou LojaJoaoBot. Se já estiver em uso, o BotFather pede outro.
5. Pronto: a resposta traz o link t.me/loja_joao_bot e, logo depois de Use this token to access the HTTP API, o token do bot.

Escolha o username com calma: diferente do nome, ele não pode ser trocado depois.

Passo 2: copie e guarde o token

O token tem o formato 123456789:AAEexampleTokenReplaceWithYours e funciona como a senha do bot: quem tiver o token controla o bot por completo. Não publique no GitHub, não coloque em código de front-end e não mande em prints. Guarde-o numa variável de ambiente:

export TELEGRAM_BOT_TOKEN="123456789:AAEexampleTokenReplaceWithYours"

Perdeu ou vazou o token? Veja como encontrar, testar e revogar o token do bot.

Passo 3: teste o token com getMe

Toda chamada segue o formato https://api.telegram.org/bot<token>/NOME_DO_METODO — repare no prefixo bot colado ao token. O método getMe é o teste mais simples:

curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe"

Com o token certo, a resposta traz os dados do bot (versão resumida):

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "Loja do João",
    "username": "loja_joao_bot"
  }
}

Sem terminal? Abra o Bot API Tester no método getMe, cole o token e execute: a requisição sai do seu navegador direto para api.telegram.org.

Passo 4: envie a primeira mensagem (curl e Python)

Bots não podem iniciar conversas. Então abra o link do seu bot e toque em Iniciar — isso envia /start. Depois, busque os updates:

curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates"

Na resposta, procure "chat":{"id":123456789,...}: esse número é o seu chat id. Em grupos e canais o caminho é outro; veja como pegar o chat id no Telegram. Agora envie a mensagem com sendMessage:

curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Olá! Meu primeiro bot está funcionando."}'

O mesmo em Python, com requests:

import os
import requests

token = os.environ["TELEGRAM_BOT_TOKEN"]
resp = requests.post(
    f"https://api.telegram.org/bot{token}/sendMessage",
    json={"chat_id": 123456789, "text": "Olá do Python!"},
    timeout=10,
)
print(resp.json())  # {"ok": true, "result": {...}}

Passo 5: um bot em Python que responde

Para o bot reagir às mensagens, um programa precisa ficar rodando. Este eco usa long polling: timeout=30 mantém a conexão aberta até chegar algo, e offset confirma os updates já processados.

import os
import requests

API = f"https://api.telegram.org/bot{os.environ['TELEGRAM_BOT_TOKEN']}"
offset = None

while True:
    resp = requests.get(f"{API}/getUpdates",
                        params={"offset": offset, "timeout": 30}, timeout=40)
    for update in resp.json()["result"]:
        offset = update["update_id"] + 1
        msg = update.get("message")
        if msg and "text" in msg:
            requests.post(f"{API}/sendMessage", json={
                "chat_id": msg["chat"]["id"],
                "text": "Você disse: " + msg["text"],
            }, timeout=10)

Rode com python bot.py, escreva para o bot e pare com Ctrl+C.

Passo 6 (opcional): descrição e comandos

• /setdescription — texto da tela inicial do chat vazio (What can this bot do?), até 512 caracteres.
• /setabouttext — bio do perfil, até 120 caracteres; /setuserpic — foto do bot.
• /setcommands — lista de comandos, uma linha por comando no formato ajuda - Como usar o bot. Eles aparecem quando o usuário digita /.

Os comandos também podem ser definidos pela API, com setMyCommands:

curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"commands": [{"command": "start", "description": "Começar"}, {"command": "ajuda", "description": "Como usar o bot"}]}'

Próximos passos: webhook, bibliotecas e Mini Apps

• Polling ou webhook: o getUpdates é ótimo para desenvolver. Em produção, muitos bots usam webhook — o Telegram envia cada update para uma URL HTTPS sua. Os dois não funcionam ao mesmo tempo. Veja como configurar o webhook do bot.
• Bibliotecas: em Python, python-telegram-bot e aiogram; em Node.js, grammY e Telegraf. Elas cuidam de polling, webhook, comandos e teclados.
• Mini Apps: interfaces web que abrem dentro do Telegram. Teste a API Telegram.WebApp no Mini App Tester.

Problemas comuns

• 401 Unauthorized: token errado, incompleto ou revogado.
• 404 Not Found: URL errada — quase sempre falta o prefixo bot antes do token.
• "result": [] no getUpdates: não há mensagens novas (envie /start de novo) ou outro programa já consumiu os updates. Eles ficam guardados por no máximo 24 horas.
• 409 Conflict: há um webhook ativo (chame deleteWebhook) ou duas instâncias do bot fazem polling com o mesmo token.
• Forbidden: bot can't initiate conversation with a user: a pessoa ainda não tocou em Iniciar no chat do bot.