Tutorial da API de Bots do Telegram: Crie seu Primeiro Bot

O tutorial mais rápido da API de Bots do Telegram se resume a três comandos: obter um token do BotFather, chamar getUpdates para ler mensagens e chamar sendMessage para responder. Todo o restante do desenvolvimento de bots se baseia nesse ciclo. Este guia percorre o caminho completo, desde sua primeira requisição cURL até um bot funcionando com um webhook e uma biblioteca.

A API de Bots é uma interface HTTP, o que significa que você pode testá-la com curl antes mesmo de escrever uma única linha de código de aplicação. Isso a torna uma das APIs mais amigáveis para aprender. Se você é um desenvolvedor que quer um bot funcionando hoje, ou um construtor avaliando código versus uma plataforma no-code como TeleClaw, você está no lugar certo.

Ao final, você entenderá como a API autentica requisições, como receber e enviar mensagens, a diferença entre long polling e webhooks, e os limites de taxa que pegam a maioria dos primeiros bots de surpresa.

Principais pontos

• Um bot é apenas um cliente HTTP. Cada método é uma requisição para https://api.telegram.org/bot<TOKEN>/METHOD_NAME, então cURL é suficiente para começar.
• Três métodos essenciais para começar: getMe para verificar o token, getUpdates para ler mensagens e sendMessage para responder.
• Long polling e webhooks são mutuamente exclusivos. Use polling para testes locais, mude para um webhook para produção.
• A API é gratuita, mas o Telegram limita o envio em massa a aproximadamente 30 mensagens por segundo para usuários diferentes e uma por segundo por chat.
• Uma biblioteca economiza tempo quando seu bot cresce além de um script. Use python-telegram-bot, aiogram ou Telegraf.

O que é a API de Bots do Telegram?

A API de Bots do Telegram é uma interface baseada em HTTP para conectar seu código ao Telegram através de um bot. De acordo com a introdução para desenvolvedores do Telegram, bots são contas especiais que não exigem um número de telefone e servem como uma interface para o código rodando em seu servidor.

Cada requisição que você faz é autenticada com um token de bot, em vez de uma conta de usuário. O token identifica o bot, então você deve tratá-lo como uma senha e nunca o enviar para um repositório público. A documentação do Telegram diz claramente: salve seu token em um lugar seguro e não o compartilhe.

A API em si é gratuita. O Telegram oferece a API de Bots gratuitamente desde o seu lançamento, sem taxa por mensagem e sem limite de quantos bots você pode criar. É por isso que tantas ferramentas da comunidade, assistentes de suporte e automações rodam nela. Se você é novo na plataforma, nosso guia sobre como criar um bot do Telegram aborda a configuração da conta em mais detalhes.

Passo 1: Obtenha um token de bot do BotFather

Abra o Telegram e procure por @BotFather, o bot oficial para criar e gerenciar outros bots. Inicie um chat e envie o comando /newbot.

O BotFather então pedirá duas coisas em sequência:

1. Um nome de exibição para seu bot, como “Meu Primeiro Bot API”.
2. Um nome de usuário que termine em bot, como meu_primeiro_bot_demo_bot.

Ao finalizar, o BotFather retornará um token de API que se parece com 123456789:AAExampleTokenStringHere. Este token é a única credencial que você precisará para o restante deste tutorial.

Atenção: Qualquer pessoa com seu token controla seu bot. Mantenha-o em uma variável de ambiente, não no código-fonte. Se ele vazar, envie /revoke para o BotFather e obtenha um novo.

Passo 2: Chame seu primeiro método da API de Bots

Antes de escrever qualquer programa, confirme se o token funciona. O método getMe retorna informações básicas sobre seu bot e é o teste de saúde padrão. Substitua <YOUR_TOKEN> pelo valor do BotFather.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Uma resposta bem-sucedida é um JSON com "ok": true e o ID, nome e nome de usuário do seu bot. Se você vir "ok": false, o token está incorreto ou tem um erro de digitação.

Essa única requisição é o padrão completo. Cada método da API de Bots do Telegram segue a mesma estrutura: uma chamada HTTPS para https://api.telegram.org/bot<TOKEN>/METHOD_NAME, com parâmetros na string de consulta ou corpo POST, e um objeto JSON em retorno. A lista completa está na referência da API de Bots, que documenta cada método e objeto que você precisará.

Passo 3: Receba e envie mensagens

Agora, torne o bot útil. Há uma regra que surpreende os iniciantes: um bot não pode iniciar uma conversa. O usuário precisa enviar uma mensagem para o bot primeiro. Então, abra seu bot no Telegram e envie qualquer texto, como “olá”.

Em seguida, leia essa mensagem com getUpdates, que busca atualizações recebidas usando long polling e retorna um array de objetos de atualização.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

Na resposta, encontre message.chat.id. Esse chat_id é o endereço para o qual você responderá. Copie-o e, em seguida, chame sendMessage:

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Olá do meu primeiro bot"

Seu bot responde no chat. Essa ida e volta, ler com getUpdates e responder com sendMessage, é o ciclo central por trás da maioria dos bots do Telegram. O parâmetro text aceita até 4096 caracteres por mensagem, então respostas longas precisam ser divididas.

Dois detalhes para lembrar ao escalar este exemplo da API de bots do Telegram para um código real:

• Recalcule o offset. Passe o update_id da última atualização mais um como o parâmetro offset na sua próxima chamada getUpdates, ou o Telegram continuará retornando as mesmas atualizações.
• Um método por vez. getUpdates para de funcionar no momento em que você registra um webhook, que é o tópico do próximo passo.

Passo 4: Escolha long polling ou um webhook

O Telegram oferece duas maneiras de receber atualizações, e você só pode usar uma por bot de cada vez.

• Long polling significa que seu código chama getUpdates repetidamente. É o caminho mais fácil para aprendizado e desenvolvimento local porque não precisa de uma URL pública, apenas um processo que continue rodando.
• Webhooks significam que o Telegram envia cada atualização para seu endpoint HTTPS como uma requisição POST no instante em que ela acontece. Este é o padrão de produção: menor latência, sem polling ocioso e escala melhor sob tráfego constante.

Para mudar para um webhook, registre sua URL HTTPS pública uma vez:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://seudominio.com/webhook"

Seu endpoint precisa de um certificado TLS válido e deve retornar HTTP 200 rapidamente. Se as atualizações pararem de chegar, a primeira medida é sempre inspecionar o erro. Para o fluxo completo de registro, verificação e solução de problemas, consulte nosso guia de configuração de webhook para bots do Telegram. A versão curta: comece com polling enquanto você constrói, mude para um webhook antes de lançar.

Passo 5: Encapsule a API em uma biblioteca

cURL puro é ótimo para aprender, mas bots de produção usam uma biblioteca. Uma biblioteca lida com as chamadas da API, análise de atualizações, retentativas e estado da conversa, para que você escreva apenas a lógica específica do seu bot. O Telegram lista bibliotecas da comunidade para quase todas as linguagens em sua página de exemplos da API de Bots.

Escolha pela linguagem que você já conhece:

• Python: python-telegram-bot é Python puro, totalmente assíncrono e suporta Python 3.10 e superior. aiogram e pyTelegramBotAPI são alternativas populares.
• Node.js: Telegraf é maduro e amigável ao TypeScript. node-telegram-bot-api é uma opção de longa data.

Aqui está o mesmo bot de eco em Python, o ponto de partida mais comum para um tutorial da API de bots do Telegram em Python:

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

TOKEN = "YOUR_TOKEN"

async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
 await update.message.reply_text(update.message.text)

app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()

E o equivalente em Node.js com Telegraf:

import { Telegraf } from 'telegraf'

const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()

Ambos fazem o mesmo trabalho que o loop cURL do Passo 3, mas em poucas linhas e com as partes complicadas tratadas para você. Maria, uma desenvolvedora de backend prototipando um bot de suporte, passou dos testes cURL para o python-telegram-bot em uma tarde e já tinha manipuladores de comando e botões inline funcionando no mesmo dia. Os conceitos da API foram transferidos diretamente porque a biblioteca é um invólucro fino sobre os mesmos métodos HTTP.

Limites de taxa e cotas a serem conhecidos

A API é gratuita, mas não é ilimitada. O FAQ de Bots do Telegram lista as diretrizes que impedem seu bot de ser limitado.

• Uma mensagem por segundo por chat. Em uma única conversa, evite enviar mais rápido que isso.
• Cerca de 30 mensagens por segundo no total ao enviar para muitos usuários diferentes. Ultrapasse e você começará a receber respostas HTTP 429 “Too Many Requests”.
• Aproximadamente 20 mensagens por minuto para o mesmo grupo.

Quando uma transmissão realmente precisa de mais, você pode habilitar as Transmissões Pagas (Paid Broadcasts) no @BotFather, o que eleva o limite para cerca de 1000 mensagens por segundo. Mensagens além das 30 gratuitas por segundo custam 0.1 Telegram Stars cada. A maioria dos bots nunca precisa disso, mas é bom saber que o limite existe antes de projetar um recurso de notificação.

Respeite um 429 lendo o valor retry_after que o Telegram retorna e pausando por essa quantidade de segundos. Uma biblioteca lida com isso para você, o que é mais um motivo para sair das requisições brutas quando seu tráfego for real.

Pule o código: Bots de IA sem um servidor

Nem todo projeto precisa de uma base de código personalizada. Se seu objetivo é um assistente de IA em um grupo do Telegram, a API de Bots é uma infraestrutura que você talvez não queira manter por conta própria, especialmente a camada de hospedagem, HTTPS e webhook.

TeleClaw é uma plataforma no-code que executa o bot para você e conecta o Claude AI de forma nativa. Você adiciona @claw ao seu grupo, cola seu token do BotFather no painel e configura o comportamento sem precisar tocar em setWebhook ou lidar com limites de taxa. Tomas, que administra uma comunidade de criptomoedas com 4.000 membros, substituiu um bot personalizado semi-acabado pelo TeleClaw e teve moderação de IA e respostas a FAQs funcionando na mesma noite.

É a mesma API de Bots por baixo. Você está escolhendo se quer operar a camada do servidor por conta própria ou deixar uma plataforma fazer isso. Explore o que isso cobre na página de recursos do TeleClaw e compare as opções em nosso resumo dos melhores bots do Telegram. Para uma construção puramente via painel, consulte nosso guia de chatbot do Telegram sem código.

Conclusão

Agora você tem um modelo mental funcional da API de Bots do Telegram: um token do BotFather, métodos HTTP como getMe, getUpdates e sendMessage, uma escolha entre long polling e webhooks, e uma biblioteca para encapsular tudo quando seu bot crescer. A API é gratuita, bem documentada e acessível o suficiente para testar com cURL em minutos.

O próximo passo mais rápido é o menor. Abra o @BotFather, execute /newbot e envie sua primeira requisição getMe para confirmar o token. A partir daí, você pode construir em Python ou Node, ou pular o servidor completamente. Para lançar um bot com IA em minutos em vez de dias, adicione @claw ao seu grupo e configure-o no painel do TeleClaw.