Crie já

API do Telegram com Python: Bot API, MTProto e Contas Vinculadas

Guia de Implementação em Python

O API do Telegram em Python guia: código funcional para cada abordagem

Um passo a passo baseado em código do API do Telegram Bot para Pythono sendMessage ligar com solicitações, um bot minimalista com python-telegram-bot, uma conta real vinculada com Telethon, Pyrogram ou o SDK da Unipile, e como lidar com limites de taxa sem que seu script caia no primeiro 429. Quer você tenha chegado aqui procurando por um API de bot do Telegram em Python exemplo ou o completo API do Telegram em Python foto, cada abordagem abaixo vem com código funcional.


Construir com Unipile


Leia a documentação



telegram_bot.py
import solicitações TOKEN = "123456:ABC-your-bot-token" url = f"https://api.telegram.org/bot{TOKEN}/sendMessage" carga útil = { "chat_id": 123456789, "texto": "Olá do Python", "modo de análise": "MarkdownV2" } response = pedidos.postagem(url, json=payload) print(resposta.json())
200 OK: mensagem enviada
Guia de Decisão

Três maneiras de construir a API do Telegram em Python e qual escolher

Assim que você tiver as credenciais, há três maneiras concretas de conversar com o Telegram a partir de uma base de código Python. Elas não são bibliotecas intercambiáveis para a mesma função: cada uma se autentica como um tipo diferente de remetente, com código diferente e restrições diferentes.
API do Telegram Bot para Python
Um token de bot do BotFather, chamado em Python com solicitações ou uma biblioteca wrapper como python-telegram-bot. A maneira mais rápida de enviar, mas um bot só pode enviar uma mensagem para um usuário que tenha escrito para ele primeiro.
Melhor para notificações e bots de suporte
Telethon / Pyrogram (MTProto)
Uma biblioteca cliente Python que fala o protocolo bruto do Telegram com o seu próprio api_id e api_hash. Faz login como uma conta real, mas você possui o armazenamento da sessão, reconexões e o fluxo de 2FA.
Melhor para um cliente Python totalmente personalizado
SDK Python do UnipileUnipile
Uma conta vinculada, chamada a partir de Python com algumas linhas de SDK em vez de um cliente MTProto bruto. Nenhum arquivo de sessão para persistir, nenhum fluxo de 2FA para programar você mesmo.
Melhor para enviar rápido sem possuir MTProto
Esta seção trata do código em Python assim que você tiver as credenciais. Para a arbitragem completa entre a Bot API e a Telegram Client API (limites, identidade, o que cada uma pode e não pode fazer), consulte nossa comparação dedicada: API do Bot do Telegram vs API do Telegram. Para obter o token do seu bot ou api_id / api_hash em primeiro lugar, veja o guia de acesso passo a passo.


Construa sua integração em Python
Tutorial de Código

A API do Python Telegram Bot com requests

A maneira mais direta de chamar o API do Bot do Telegram em Python é uma chamada HTTP simples com solicitações, sem nenhuma biblioteca wrapper envolvida. A partir da Bot API 10.2 (14 de julho de 2026), um token de bot do BotFather e dois parâmetros são tudo o que sendMessage requer.
1
Obtenha um token de bot e, em seguida, chame sendMessage
O BotFather emite um token com o formato de 123456:ABC-your-bot-token. Cada chamada da API do Bot, incluindo sendMessage, é um POST para https://api.telegram.org/bot<TOKEN>/sendMessage com um corpo JSON.



send_message.py
import os import solicitações TOKEN = os.meio ambiente["TELEGRAM_BOT_TOKEN"] URL = f"https://api.telegram.org/bot{TOKEN}/sendMessage" carga útil = { "chat_id": 123456789, "texto": ""Seu pedido #4821 já foi enviado."", "modo de análise": "MarkdownV2" } response = pedidos.postagem(URL, json=payload, timeout=10)
2
Verifique a resposta, não assuma que funcionou
A Bot API sempre responde com um corpo JSON contendo um ok booleano. Um código de status diferente de 200 ou ok: false significa que a mensagem não foi enviada, e a carga útil inclui uma legível por humanos descrição para registrar.



send_message.py
dados = resposta.json() se response.status_code == 200 e dados.obter("ok"): id_da_mensagem = dados["resultado"]["message_id"] print(f"enviado, message_id={message_id}") senão: print(f"falha: {data.get('description')}")
ParâmetroTipoDescrição
chat_id Obrigatórioint ou strIdentificador do chat de destino, ou @username para um canal público.
text ObrigatóriostrTexto da mensagem, 1 a 4096 caracteres após a análise de entidades.
modo de análise OpcionalstrMarkdownV2 ou HTML, para renderizar formatação de negrito, links e código no texto.
desativar_notificação OpcionalbooleanoEnvia a mensagem silenciosamente, sem som de notificação push.
parâmetros_de_resposta OpcionaldicionárioEnvia a mensagem como uma resposta a uma mensagem existente no chat.


Supere o limite exclusivo para bots
Tutorial de Código

A API do Telegram Bot em Python com python-telegram-bot

Cru solicitações as chamadas funcionam bem para uma única mensagem de saída. Além disso, a maioria das bases de código em Python envolvem a API do bot do Telegram em python-telegram-bot, uma biblioteca que transforma os mesmos endpoints HTTP em um modelo de objeto Python assíncrono com polling de atualização integrado.
O que a biblioteca adiciona em relação ao uso bruto de requests
Um Aplicativo objeto que gerencia o loop de atualização para você (polling ou webhook)
Métodos tipados como bot.send_message() em vez de payloads JSON construídos manualmente
Manipuladores de comandos e mensagens, portanto, respondendo a /iniciar é um decorador, não um loop
Os parâmetros são os mesmos abordados acima: chat_id, text, modo de análise. A biblioteca ainda não consegue fazer com que um bot envie uma mensagem para um usuário primeiro; essa restrição está nas regras da plataforma do Telegram, não no cliente que você usa para chamá-la.



bot.py
from telegrama import Atualizar from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes assíncrono def iniciar(update: Update, context: ContextTypes.DEFAULT_TYPE): await contexto.bot.enviar_mensagem( chat_id=update.effective_chat.id, A tradução para o português do Brasil seria: "texto=""Olá do python-telegram-bot", parse_mode="MarkdownV2" ) aplicativo = ApplicationBuilder().token("123456:ABC-your-bot-token").construir() app.add_handler(Manipulador de Comandos("start", início)) aplicativo.executar_polling()
API do Cliente / MTProto

Uma conta de usuário real em Python: Telethon e Pyrogram

Enviar como uma conta real do Telegram a partir do Python, e não como um bot, significa usar a Client API com api_id e api_hash do my.telegram.org. Duas bibliotecas Python fazem o trabalho pesado do MTProto: Telethon e Pyrogram.
Python

Telethon

Uma implementação de MTProto em puro Python construída em torno de async/await, com uma API de cliente que se parece mais com Python simples do que com chamadas de protocolo brutas.
Python

Pyrogram

Outro cliente Python MTProto, com sua própria abordagem de gerenciamento de sessões e uma interface de cliente projetada para parecer um SDK convencional em vez de uma biblioteca de protocolo.



telethon_client.py
from telethon import TelegramClient from telethon.errors import SessionPasswordNeededError api_id = 1234567 api_hash = "seu_api_hash_de_my.telegram.org" # "my_account" é o nome do arquivo de sessão no disco, reutilizado a cada execução client = TelegramClient("minha_conta", api_id, api_hash) assíncrono def principal(): await cliente.iniciar(telefone="+15551234567") await cliente.enviar_mensagem("nome_de_usuario_ou_id", "Olá do Telethon") com cliente: client.loop.executar_ate_completar(main())
A barreira de 2FA que todo login caseiro precisa enfrentar
1
Enviar o código de login
client.start(phone=...) enrolados auth.sendCode, que envia um código de login por SMS para o número de telefone e retorna um hash_do_codigo_do_telefone usado para a próxima chamada.
2
Validar o código
A biblioteca solicita o código e chama auth.signIn com isso. É aqui que uma implementação focada apenas no caminho feliz para.
3
SESSÃO_SENHA_NECESSÁRIA
Se a conta tiver a autenticação de dois fatores ativada, o Telegram responde com um Erro 400: SESSION_PASSWORD_NEEDED. O Telethon levanta isso como SessionPasswordNeededError, um branch esperado, não um bug para capturar e ignorar.
4
Resolva isso com a senha da nuvem
Passando a senha de nuvem da conta para client.start(password=...) executa a troca SRP e auth.checkPassword para você. Chamar a camada bruta do MTProto diretamente significa construir a InputCheckPasswordSRP objece-te.
Persista a sessão ou faça login a cada execução
O Telethon e o Pyrogram gravam um arquivo de sessão local (ou em memória StringSession) após o primeiro login bem-sucedido. Perca-o, ou faça o deploy sem persistí-lo, e seu script terá que executar o fluxo do código de telefone e 2FA novamente a cada reinicialização.
Erros a esperar neste caminho
SENHA_DA_SESSAO_NECESSARIA
HASH_DE_SENHA_INVALIDO
API_ID_PUBLISHED_FLOOD
Apenas os aplicativos oficiais do Telegram recebem entrega de códigos SMS baseada no Firebase. Um script em Python também precisa do seu api_id do my.telegram.org: reutilizar o ID de exemplo fornecido no código de exemplo de código aberto aciona API_ID_PUBLISHED_FLOOD para os seus usuários finais, e apenas um api_id é emitido por número de telefone.
A abordagem Unipile
Para ver a lista completa de recursos do Telegram disponibilizados pelo Unipile, consulte o Página do produto da API do Telegram.

Uma conta real do Telegram em Python, sem escrever MTProto

O SDK Python da Unipile conecta uma conta de usuário existente do Telegram através do próprio Dispositivos recurso, seja uma leitura de QR code ou Hosted Auth com provedores: "TELEGRAM". Não há api_id, sem arquivo de sessão para persistir, e sem SENHA_DA_SESSAO_NECESSARIA ramificar para escrever você mesmo: a conta vinculada aparece como conectado ou não.
Assim que uma conta é vinculada, o envio de uma mensagem a partir do Python resume-se a algumas chamadas de SDK, todas executadas na infraestrutura da Unipile v2 API por trás. Iniciar chat pega o ID da conta vinculada e um IDs de usuário lista e abre uma nova conversa ou entrega na existente se já existir um chat com esse destinatário.
Não api_id / api_hash par para solicitar ou alternar
Nenhum arquivo de sessão, nenhum handshake SRP, nenhum branch de 2FA no seu código
Mesmo tratamento de status de conta para gerenciamento de participantes do grupo
A instalação do SDK não é abordada aqui, pois o nome exato do pacote é melhor confirmado na documentação atual, veja developer.unipile.com/docs/getting-started para a etapa de instalação e a referência completa do Python.
Cada recurso mostrado aqui é listado endpoint por endpoint no Página do produto da API do Telegram da Unipile, incluindo o que é suportado e o que não é.



send_telegram.py
import unipilar configuração = unipile.Configuração() configuration.api_key["apiKey"] = "chave de API" cliente_api = unipile.ApiClient(configuração) API de mensagens = unipile.MessagingApi(api_client) chat = api_de_mensagens.Iniciar chat( "acc_123456789", {"ids_de_usuario": ["0123456789"], "texto": "Olá, dando seguimento à sua solicitação."} )
O que a integração do Telegram do Unipile não cobre
Canais, comunidades e transmissões
Administração do grupo: aprovar ou promover membros
Arquivamento de chat
Chamadas de voz e vídeo
Construa com o SDK do Python
Erros e limites

Tratamento de erros e limites de taxa em Python

Um script que envia uma mensagem em um chat de teste e um script que roda em produção enfrentam problemas diferentes. O segundo eventualmente recebe um 429 ou um FLOOD_WAIT_X, e o que o seu código Python fizer a seguir decide se isso é uma pausa de cinco segundos ou uma conta banida.
1/s
Número máximo de mensagens da API do Bot para o mesmo chat individual
20/min
Número máximo de mensagens da API do Bot dentro de um único grupo
~30/seg
Limite aproximado da API de Bot ao transmitir para chats
429
Status retornado assim que qualquer um desses limites for ultrapassado
Loops de tentativa para ambos os lados da API
A API do Bot e a API do Cliente sinalizam o mesmo problema com duas formas diferentes. Ambas precisam ser capturadas explicitamente, e não registradas em log e retidas cegamente.



bot_api_retry.py
import tempo import solicitações def enviar_com_nova_tentativa(url, payload, max_retries=3): para tentativa em intervalo(tentativas_max) r = pedidos.postagem(url, json=payload) se r.status_code != 429: return r tentar_novamente_apos = r.json().obter("parâmetros", {}).obter("tente_novamente_apos", 1) tempo.dormir(tente_novamente_em) levantar Erro de tempo de execução("muitas respostas 429")



telethon_flood_wait.py
from telethon.errors import FloodWaitError import asyncio assíncrono def enviar_com_segurança(cliente, entidade, texto) tentar: await cliente.enviar_mensagem(entidade, texto) exceto FloodWaitError como e: # e.seconds é o valor de FLOOD_WAIT_X que o Telegram devolveu await asyncio.dormir(e.seconds) await cliente.enviar_mensagem(entidade, texto)
Orientação de ritmo que mantém você abaixo dos limites desde o início
Evite enviar um volume alto de contas recém-criadas, eles são sinalizados mais rapidamente do que os estabelecidos.
Aumentar o volume de envio progressivamente em vez de iniciar um script com vazão total.
Mantenha pelo menos 10 a 20 segundos entre mensagens enviadas da mesma conta, esta é a recomendação da própria Unipile para contas vinculadas, não apenas um limite da API do Bot.
Resumo

API do Python Telegram Bot vs Telethon/Pyrogram vs SDK do Unipile

O mesmo resumo em formato de tabela: o que cada caminho em Python realmente exige e onde ele para.
DimensãoBot API (requests / python-telegram-bot)Telethon / Pyrogram (MTProto)SDK Python do Unipile
Pode enviar mensagem para um usuário primeiroNãoSim, dependente de privacidadeSim
Requisito de configuraçãoToken do bot do BotFatherapi_id / api_hash de my.telegram.orgConta vinculada via código QR ou Autenticação Hospedada
Gerenciamento de sessãoBaseado em token, nada para persistirVocê mesmo persiste o arquivo de sessãoGerenciado pelo recurso de Dispositivos do próprio Telegram
2FA / SESSION_PASSWORD_NEEDEDNão se aplicaVocê lida com a troca do SRPResolvido para você
Participantes do grupo (obter / adicionar / remover)Limitado às permissões do botSim, autoconstruídoSim, endpoints v2 dedicados
Canais, comunidades, transmissõesSim, se adicionado como administradorSimNão suportado
Melhor paraBots de notificação e suporteUm cliente MTProto em Python totalmente personalizadoEnviando rápido sem possuir o MTProto
Pode enviar mensagem para um usuário primeiro
API de BotNão
Telethon / PyrogramSim, dependente de privacidade
SDK UnipileSim
Requisito de configuração
API de BotToken do bot
Telethon / Pyrogramapi_id / api_hash
SDK UnipileConta vinculada
Gerenciamento de sessão
API de BotNada para persistir
Telethon / PyrogramSessão autopersistida
SDK UnipileGerenciado via Dispositivos
2FA / SESSION_PASSWORD_NEEDED
API de BotNão se aplica
Telethon / PyrogramSRP autoconstruído
SDK UnipileResolvido para você
Participantes do grupo (obter / adicionar / remover)
API de BotLimitado às permissões do bot
Telethon / PyrogramAutoconstruído
SDK UnipileEndpoints v2 dedicados
Canais, comunidades, transmissões
API de BotSim, como administrador
Telethon / PyrogramSim
SDK UnipileNão suportado
Melhor para
API de BotNotificações, bots de suporte
Telethon / PyrogramCliente totalmente personalizado
SDK UnipileEnvio rápido, sem MTProto
Construa com o SDK da Unipile

API do Telegram em Python - FAQ

Perguntas comuns sobre a API do Python Telegram Bot, python-telegram-bot, Telethon, Pyrogram e como conectar uma conta real com o Unipile.

Sim. O API do bot do Telegram é uma interface HTTP simples, portanto, uma única POST requisição com o Python solicitações biblioteca para https://api.telegram.org/bot<TOKEN>/sendMessage, com um chat_id e text no corpo JSON, é suficiente. Nenhum SDK ou biblioteca wrapper é necessário para esta chamada.

O API do bot do Telegram é a interface HTTP própria do Telegram, que pode ser chamada a partir do Python com solicitações ou qualquer cliente HTTP. python-telegram-bot é uma biblioteca Python de terceiros que encapsula esses mesmos endpoints HTTP em um modelo de objeto assíncrono, com um Aplicativo classe, métodos tipados como bot.send_message, e verificação de atualizações integrada ou manipulação de webhooks.

Esta é uma regra estrutural da Bot API, não um bug no seu código. Um bot não pode chamar sendMessage contra um chat_id até que esse usuário tenha enviado pelo menos uma mensagem para o bot primeiro. Nenhum parâmetro ou biblioteca Python contorna isso. Uma conta real do Telegram vinculada, através do Telethon, Pyrogram ou do SDK Unipile, não tem essa restrição.

Não. A API do Bot precisa apenas de um token de bot emitido pelo BotFather. api_id e api_hash do my.telegram.org são necessários para a Client API (MTProto), o protocolo usado pelo Telethon, Pyrogram e qualquer cliente que faça login como uma conta de usuário real em vez de um bot.

SENHA_DA_SESSAO_NECESSARIA é um erro 400 que o Telegram retorna de auth.signIn quando a conta tem a autenticação de dois fatores ativada. O Telethon lança isso como SessionPasswordNeededError. Limpá-lo significa executar o protocolo SRP e chamar auth.checkPassword com a senha de nuvem da conta, que tanto o Telethon quanto o Pyrogram gerenciam quando você passa a senha para o método de login deles.

A API do Bot retorna um 429 status assim que você excede cerca de uma mensagem por segundo para o mesmo chat, 20 mensagens por minuto em um grupo, ou cerca de 30 mensagens por segundo ao transmitir entre chats. A resposta inclui um tentar_novamente_apos valor em segundos. Do lado do MTProto, o equivalente é um ENCHENTE 420 erro ou um FLOOD_WAIT_X exceção, onde X é o número de segundos a esperar antes de tentar novamente.

Sim. O SDK Python do Unipile conecta uma conta de usuário existente do Telegram através do próprio recurso Dispositivos do Telegram, seja por leitura de código QR ou Autenticação Hospedada, e expõe o envio de mensagens por meio de algumas chamadas de SDK, tais como Iniciar chat. Não há api_id para solicitar, sem implementação de MTProto e sem arquivo de sessão ou ramificação de 2FA para escrever sozinho.

O gerenciamento de participantes do grupo é suportado: listar, adicionar e remover participantes por meio de recursos dedicados v2 endpoints. Canais, comunidades, transmissões, ações de administração de grupo, como aprovar ou promover membros, arquivamento de chats e chamadas de voz ou vídeo não são suportados.

Ainda tem dúvidas? Nossa equipe está aqui para ajudar.

Fale com um especialista
API do Telegram em Python, do jeito certo

Crie sua integração do bot da API do Telegram em Python com a Unipile

Ignore os arquivos de sessão do MTProto, ignore a limitação exclusiva para bots. Conecte uma conta existente do Telegram através do SDK Python da Unipile e unifique-a com WhatsApp, LinkedIn, Instagram, Gmail, Outlook e IMAP em uma única API.
Construir com Unipile
Leia a documentação Consulte a página da API do Telegram
Obtendo acesso à API do Telegram, passo a passo
Enviar uma mensagem no Telegram com a API
API do Bot do Telegram vs API do Telegram
Página do produto da API do Telegram da Unipile
pt_BRBR
en_USEN fr_FRFR es_ESES de_DEDE it_ITIT nl_NLNL pl_PLPL tr_TRTR pt_BRBR