LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Outlook
Calendario de Google
Únase a la comunidad Slack Índice
API de Bot en Python
Más allá de MTProto
Guía de implementación de Python
En API de Telegram en Python guía: código funcional para cada enfoque
Un recorrido centrado en el código del API de Python para Telegram Botel
sendMessage llamada con solicita, un bot minimalista con python-telegram-bot, una cuenta real vinculada con Telethon, Pyrogram o el SDK de Unipile, y cómo gestionar los límites de velocidad (rate limits) sin que tu script se caiga en el primer 429. Ya sea que hayas llegado aquí buscando un API de bot de Telegram en Python ejemplo o el completo API de Telegram en Python imagen, cada enfoque a continuación se entrega con código funcional.import solicita
TOKEN = "123456:ABC-your-bot-token"
url = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
carga útil = {
"chat_id": 123456789,
"texto": "Hola desde Python",
"modo_analisis": "MarkdownV2"
}
response = solicitudes.Correo electrónico:(url, json=payload)
print(respuesta.json())200 OK: mensaje enviado
Guía de decisión
Tres formas de construir la API de Telegram en Python y cuál elegir
Una vez que tengas las credenciales, hay tres formas concretas de comunicarse con Telegram desde una base de código en Python. No son bibliotecas intercambiables para la misma tarea: cada una se autentica como un tipo diferente de remitente, con código diferente y restricciones distintas.
API de Python para Telegram Bot
Un token de bot de BotFather, llamado desde Python con
Ideal para notificaciones y bots de soporte solicita o una biblioteca contenedora como python-telegram-bot. La forma más rápida de enviar, pero un bot solo puede enviar un mensaje a un usuario que le haya escrito primero.Telethon / Pyrogram (MTProto)
Una biblioteca cliente de Python que habla el protocolo puro de Telegram con el tuyo
Ideal para un cliente de Python totalmente personalizado api_id y api_hash. Inicia sesión como una cuenta real, pero tú controlas el almacenamiento de la sesión, las reconexiones y el flujo de autenticación de doble factor (2FA).SDK de Python de UnipileUnipile
Una cuenta vinculada, llamada desde Python con unas pocas líneas del SDK en lugar de un cliente MTProto sin procesar. Sin archivos de sesión que persistir, sin rama de 2FA que escribir tú mismo.
Lo mejor para realizar envíos rápidos sin poseer MTProto Esta sección trata sobre el código de Python una vez que tienes las credenciales. Para ver la comparación completa entre la API de bots y la API de cliente de Telegram (límites, identidad, lo que cada una puede y no puede hacer), consulta nuestra comparación dedicada: API de Telegram Bot vs API de Telegram. Para obtener el token de tu bot o
api_id / api_hash en primer lugar, vea el guía de acceso paso a paso.Crea tu integración en Python
Tutorial de código
La API de Python Telegram Bot con requests
La forma más directa de llamar al API de Telegram Bot en Python es una llamada HTTP simple con
solicita, sin involucrar ninguna biblioteca contenedora. A partir de la API de Bot 10.2 (14 de julio de 2026), un token de bot de BotFather y dos parámetros son todo lo que sendMessage requiere.1
Obtén un token de bot, luego llama a sendMessage
BotFather emite un token con la forma de
123456:ABC-your-bot-token. Cada llamada a la API de Bot, incluidas sendMessage, es un POST a https://api.telegram.org/bot<TOKEN>/sendMessage con un cuerpo JSON.import os
import solicita
TOKEN = os.alrededor["TELEGRAM_BOT_TOKEN"]
URL = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
carga útil = {
"chat_id": 123456789,
"texto": "Tu pedido #4821 ya se ha enviado".",
"modo_analisis": "MarkdownV2"
}
response = solicitudes.Correo electrónico:(URL, json=payload, timeout=10)2
Verifica la respuesta, no asumas que funcionó
La Bot API siempre responde con un cuerpo JSON que contiene un
de acuerdo booleano. Un código de estado que no sea 200 o ok: false significa que el mensaje no fue enviado y el contenido incluye una descripción legible por humanos descripción iniciar sesión.datos = respuesta.json()
si response.status_code == 200 y datos.consiga("de acuerdo"):
id_de_mensaje = datos["resultado"]["id_de_mensaje"]
print(f"enviado, message_id={message_id}")
si no:
print(error: {data.get("description')}')| Parámetro | Tipo | Descripción |
|---|---|---|
chat_id Requerido | int o str | Identificador de chat de destino, o @username para un canal público. |
text Requerido | cadena | Texto del mensaje, de 1 a 4096 caracteres después del análisis de entidades. |
modo de análisis Opcional | cadena | MarkdownV2 o HTML, para aplicar formato de negrita, enlaces y código en el texto. |
desactivar_notificación Opcional | booleano | Envía el mensaje en silencio, sin sonido de notificación push. |
parámetros_de_respuesta Opcional | diccionario | Envía el mensaje como respuesta a un mensaje existente en el chat. |
Superar el límite exclusivo para bots
Tutorial de código
La API de Telegram Bot en Python con python-telegram-bot
Crudo
solicita las llamadas funcionan bien para un solo mensaje saliente. Más allá de eso, la mayoría de las bases de código en Python envuelven el API del bot de Telegram en python-telegram-bot, una biblioteca que convierte los mismos puntos de conexión HTTP en un modelo de objeto de Python asíncrono con sondeo de actualizaciones integrado. Lo que la biblioteca añade sobre las peticiones sin procesar
En
Aplicación objeto que gestiona el bucle de actualización por ti (sondeo o webhook)Métodos tipados como
bot.send_message() en lugar de payloads de JSON construidos a manoControladores de comandos y mensajes, por lo que responder a
/inicio es un decorador, no un bucleLos parámetros son los mismos que se cubrieron anteriormente:
chat_id, text, modo de análisis. La biblioteca aún no puede hacer que un bot le envíe un mensaje a un usuario primero, esa restricción se encuentra en las reglas de la plataforma de Telegram, no en el cliente que usas para llamarla.from telegrama import Actualizar
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes
asíncrono def iniciar(update: Update, context: ContextTypes.DEFAULT_TYPE):
await context.bot.enviar_mensaje(
chat_id=update.effective_chat.id,
Hola"Hola desde python-telegram-bot",
parse_mode="MarkdownV2"
)
aplicación = ApplicationBuilder().ficha("123456:ABC-your-bot-token").construir()
app.add_handler(Gestor de comandos("inicio", inicio))
aplicación.ejecutar_sondeo()API de cliente / MTProto
Una cuenta de usuario real en Python: Telethon y Pyrogram
Enviar mensajes como una cuenta real de Telegram desde Python, y no como un bot, significa utilizar la API de cliente con
api_id y api_hash de my.telegram.org. Dos bibliotecas de Python hacen el trabajo pesado de MTProto: Telethon y Pyrogram. Python
Teletón
Una implementación de MTProto en Python puro construida en torno a async/await, con una API de cliente que se lee casi como Python plano en lugar de llamadas de protocolo sin procesar.
Python
Pyrogram
Otro cliente de Python para MTProto, con su propio enfoque en la gestión de sesiones y una interfaz de cliente diseñada para parecerse a un SDK convencional en lugar de a una biblioteca de protocolos.
from telemaratón import TelegramClient
from telethon.errors import SessionPasswordNeededError
api_id = 1234567
api_hash = "tu_api_hash_de_my.telegram.org"
# "my_account" es el nombre del archivo de sesión en el disco, que se reutiliza en cada ejecución
client = TelegramClient("mi_cuenta", api_id, api_hash)
asíncrono def principal():
await cliente.iniciar(teléfono="+15551234567")
await cliente.enviar_mensaje("nombre_de_usuario_o_id", "Hola desde Telethon")
con cliente:
client.loop.ejecutar_hasta_completar(main())1
Envía el código de inicio de sesión
cliente.start(phone=...) envolturas auth.sendCode, que envía un código de inicio de sesión por mensaje de texto al número de teléfono y devuelve un código_hash_teléfono utilizado para la próxima llamada. 2
Validar el código
La biblioteca solicita el código y las llamadas
La biblioteca solicita el código y las llamadas
auth.signIn con él. Aquí es donde se detiene una implementación exclusiva del camino feliz. 3
Pulse SESSION_PASSWORD_NEEDED
Si la cuenta tiene la autenticación de dos factores habilitada, Telegram responde con un Error 400: SESSION_PASSWORD_NEEDED. Telethon plantea esto como
Si la cuenta tiene la autenticación de dos factores habilitada, Telegram responde con un Error 400: SESSION_PASSWORD_NEEDED. Telethon plantea esto como
SessionPasswordNeededError, una rama esperada, no un error que atrapar e ignorar. 4
Acláralo con la contraseña de la nube
Pasar la contraseña en la nube de la cuenta a
Pasar la contraseña en la nube de la cuenta a
client.start(password=...) ejecuta el intercambio SRP y auth.checkPassword para ti. Llamar directamente a la capa MTProto en bruto significa construir la InputCheckPasswordSRP Objeto usted mismo. Persiste la sesión o inicia sesión en cada ejecución
Telethon y Pyrogram escriben un archivo de sesión local (o en memoria)
Telethon y Pyrogram escriben un archivo de sesión local (o en memoria)
StringSession) después del primer inicio de sesión exitoso. Póngala a perder, o desplieguela sin persistirla, y su script tendrá que volver a ejecutar el flujo de código telefónico y de 2FA en cada reinicio. CONTRASEÑA_DE_SESIÓN_NECESARIA
HASH_DE_CONTRASEÑA_INVÁLIDO
API_ID_PUBLISHED_FLOOD
HASH_DE_CONTRASEÑA_INVÁLIDO
API_ID_PUBLISHED_FLOOD
Solo las aplicaciones oficiales de Telegram reciben la entrega de códigos SMS basada en Firebase. Un script de Python también necesita el suyo
api_id desde my.telegram.org: reutilizar el ID de ejemplo incluido en el código de ejemplo de código abierto activa API_ID_PUBLISHED_FLOOD para sus usuarios finales, y solo uno api_id se emite por número de teléfono.El enfoque de Unipile
Para ver la lista completa de capacidades de Telegram expuestas por Unipile, consulte la Página de producto de la API de Telegram.
Una cuenta real de Telegram en Python, sin escribir MTProto
El SDK de Python de Unipile conecta una cuenta de usuario de Telegram existente a través del propio Telegram Dispositivos característica, ya sea un escaneo de código QR o autenticación alojada con
proveedores: "TELEGRAM". No hay api_id, no hay archivo de sesión para persistir, y no CONTRASEÑA_DE_SESIÓN_NECESARIA rama para escribir usted mismo: la cuenta vinculada aparece como conectado o no lo hace.Una vez que una cuenta está vinculada, enviar un mensaje desde Python requiere unas pocas llamadas al SDK, todo ejecutándose en la infraestructura de Unipile v2 API subyacente.
iniciar chat toma el ID de la cuenta vinculada y un ids_de_usuario lista, y abre una nueva conversación o se integra en la existente si ya hay un chat con ese destinatario.No
api_id / api_hash emparejar para solicitar o rotarNingún archivo de sesión, ningún protocolo de enlace SRP, ninguna rama de 2FA en tu código
Manejo del estado de la cuenta igual para la gestión de participantes del grupo
La instalación del SDK no se cubre aquí, ya que el nombre exacto del paquete se confirma mejor en la documentación actual; véase developer.unipile.com/docs/getting-started para el paso de instalación y la referencia completa de Python.
Cada capacidad mostrada aquí se enumera endpoint por endpoint en el Página de producto de la API de Telegram de Unipile, incluidos los aspectos compatibles y los que no lo son.
import unipile
configuración = unipile.Configuración()
configuration.api_key["apiKey"] = "clave de API"
cliente_api = unipile.ClienteApi(configuración)
API de mensajería = unipile.API de mensajería(api_client)
chat = API de mensajería.iniciar chat(
"acc_123456789",
{"IDs de usuario": ["0123456789"], "texto": "Hola, dando seguimiento a su solicitud."}
)Lo que la integración de Telegram de Unipile no cubre
Canales, comunidades y difusiones
Administración del grupo: aprobar o ascender a miembros
Archivado de chats
Llamadas de voz y vídeo
Errores y límites
Manejo de errores y límites de velocidad en Python
Un script que envía un mensaje en un chat de prueba y un script que se ejecuta en producción se enfrentan a problemas diferentes. El segundo eventualmente recibe un
429 o un ESPERA_DE_INUNDACIÓN_X, y lo que haga tu código de Python a continuación decide si eso es una pausa de cinco segundos o una cuenta suspendida. 1/s
Máximo de mensajes de la API de Bot al mismo chat individual
Máximo de mensajes de la API de Bot al mismo chat individual
20/min
Máximo de mensajes de la API de Bot dentro de un solo grupo
Máximo de mensajes de la API de Bot dentro de un solo grupo
~30/s
Límite aproximado de la API de Bots al realizar difusiones en chats
Límite aproximado de la API de Bots al realizar difusiones en chats
429
Estado devuelto una vez que se supera cualquiera de estos límites
Estado devuelto una vez que se supera cualquiera de estos límites
La API de Bot y la API de Client señalan el mismo problema con dos formas diferentes. Ambas deben capturarse explícitamente, no registrarse e intentarse de nuevo a ciegas.
import tiempo
import solicita
def enviar_con_reintento(url, payload, max_retries=3):
para intento en rango(reintentos_máximos):
r = solicitudes.Correo electrónico:(url, json=payload)
si r.status_code != 429:
return r
reintentar_después = r.json().consiga("parámetros", {}).consiga("reintentar_después", 1)
tiempo.dormir(reintentar_después)
elevar Error de tiempo de ejecución("demasiadas respuestas 429")from telethon.errors import FloodWaitError
import asyncio
asíncrono def enviar_de_forma_segura(cliente, entidad, texto):
intentar:
await cliente.enviar_mensaje(entidad, texto)
excepto FloodWaitError como e:
# e.seconds es el valor de FLOOD_WAIT_X que Telegram ha devuelto
await asíncrono.dormir(e.seconds)
await cliente.enviar_mensaje(entidad, texto) Orientación sobre el ritmo que te mantiene por debajo de los límites desde el principio
Evite enviar un volumen elevado desde cuentas nuevas, se marcan más rápido que las establecidas.
Aumentar el volumen de envío progresivamente en lugar de iniciar un script a pleno rendimiento.
Mantén al menos 10 a 20 segundos entre los mensajes enviados desde la misma cuenta, esta es la recomendación propia de Unipile para cuentas vinculadas, no solo un límite de la API de bots.
Resumen
API de Python Telegram Bot vs Telethon/Pyrogram vs SDK de Unipile
El mismo resumen en forma de tabla: qué requiere realmente cada ruta de Python y dónde se detiene.
| Dimensión | API de Bot (requests / python-telegram-bot) | Telethon / Pyrogram (MTProto) | SDK de Python de Unipile |
|---|---|---|---|
| Puede enviar un mensaje a un usuario primero | No | Sí, dependiente de la privacidad | Sí |
| Requisito de configuración | Token de bot de BotFather | api_id / api_hash desde my.telegram.org | Cuenta vinculada mediante código QR u Autenticación Alojada |
| Gestión de sesiones | Basado en tokens, nada que persistir | Tú mismo guardas el archivo de sesión | Gestionado mediante la función Dispositivos propia de Telegram |
| 2FA / SESSION_PASSWORD_NEEDED | No aplicable | Tú manejas el intercambio SRP | Manejado para ti |
| Participantes del grupo (obtener / añadir / eliminar) | Limitado a los permisos del bot | Sí, autoconstruido | Sí, endpoints v2 dedicados |
| Canales, comunidades, difusiones | Sí, si se añade como administrador | Sí | No se admite |
| Mejor para | Notificaciones y bots de soporte | Un cliente MTProto en Python totalmente personalizado | Envío rápido sin poseer MTProto |
Puede enviar un mensaje a un usuario primero
API de botsNo
Telethon / PyrogramSí, dependiente de la privacidad
SDK de UnipileSí
Requisito de configuración
API de botsToken del bot
Telethon / Pyrogramid de api / hash de api
SDK de UnipileCuenta vinculada
Gestión de sesiones
API de botsNada que persistir
Telethon / PyrogramSesión autopersistida
SDK de UnipileGestionado mediante Dispositivos
2FA / SESSION_PASSWORD_NEEDED
API de botsNo aplicable
Telethon / PyrogramSRP autoconstruido
SDK de UnipileManejado para ti
Participantes del grupo (obtener / añadir / eliminar)
API de botsLimitado a los permisos del bot
Telethon / PyrogramAutoconstruido
SDK de UnipileEndpoints v2 dedicados
Canales, comunidades, difusiones
API de botsSí, como administrador
Telethon / PyrogramSí
SDK de UnipileNo se admite
Mejor para
API de botsNotificaciones, bots de soporte
Telethon / PyrogramCliente totalmente personalizado
SDK de UnipileEnvío rápido, sin MTProto
API de Telegram en Python - Preguntas frecuentes
Preguntas frecuentes sobre la API de Python Telegram Bot, python-telegram-bot, Telethon, Pyrogram y cómo conectar una cuenta real con Unipile.
Sí. El API del bot de Telegram es una interfaz HTTP plana, por lo que una sola POST solicitud con Python solicita biblioteca para https://api.telegram.org/bot<TOKEN>/sendMessage, con un chat_id y text en el cuerpo JSON, es suficiente. No se requiere ningún SDK ni biblioteca contenedora para esta llamada.
En API del bot de Telegram es la propia interfaz HTTP de Telegram, invocable desde Python con solicita o cualquier cliente HTTP. python-telegram-bot es una biblioteca de Python de terceros que envuelve esos mismos puntos finales HTTP en un modelo de objetos asíncrono, con un Aplicación métodos de clase y tipados como bot.send_message, y sondeo de actualizaciones integrado o manejo de webhooks.
Esta es una regla estructural de la API de Bot, no un error en tu código. Un bot no puede llamar sendMessage contra un chat_id hasta que ese usuario haya enviado al menos un mensaje al bot primero. Ningún parámetro o librería de Python lo soluciona. Una cuenta real de Telegram vinculada, a través de Telethon, Pyrogram, o el SDK de Unipile, no tiene esta restricción.
No. La Bot API solo necesita un token de bot emitido por BotFather. api_id y api_hash de my.telegram.org son necesarios para la API de cliente (MTProto), el protocolo utilizado por Telethon, Pyrogram y cualquier cliente que inicie sesión como una cuenta de usuario real en lugar de un bot.
CONTRASEÑA_DE_SESIÓN_NECESARIA es un error 400 que devuelve Telegram auth.signIn cuando la cuenta tiene la autenticación de dos factores habilitada, Telethon la lanza como SessionPasswordNeededError. Limpiarlo significa ejecutar el protocolo SRP y llamar auth.checkPassword con la contraseña en la nube de la cuenta, que tanto Telethon como Pyrogram manejan cuando le pasas la contraseña a su método de inicio de sesión.
La Bot API devuelve un 429 estado una vez que superas aproximadamente un mensaje por segundo en el mismo chat, 20 mensajes por minuto en un grupo, o unos 30 mensajes por segundo al realizar transmisiones en varios chats. La respuesta incluye un reintentar_después valor en segundos. En el lado de MTProto, el equivalente es un INUNDACIÓN 420 error o un ESPERA_DE_INUNDACIÓN_X excepción, donde X es el número de segundos a esperar antes de volver a intentarlo.
Sí. El SDK de Python de Unipile conecta una cuenta de usuario de Telegram existente a través de la propia función de Dispositivos de Telegram, ya sea mediante un escaneo de código QR o Autenticación Alojada, y expone la mensajería a través de unas pocas llamadas al SDK como iniciar chat. No hay api_id para solicitar, sin implementación de MTProto, y sin archivo de sesión o rama de 2FA que escribir tú mismo.
La gestión de participantes del grupo está permitida: listar, añadir y eliminar participantes mediante funciones dedicadas v2 puntos de enlace. No se admiten canales, comunidades, transmisiones, acciones de administración de grupos como aprobar o promover miembros, archivo de chats ni llamadas de voz o video.
¿Aún tiene preguntas? Nuestro equipo está aquí para ayudarle.
API de Telegram en Python, hecha correctamente
Crea tu integración de la API de Telegram Bot con Python usando Unipile
Omitir los archivos de sesión de MTProto, omitir la limitación exclusiva de bots. Conecta una cuenta de Telegram existente a través del SDK de Python de Unipile y unifícala con WhatsApp, LinkedIn, Instagram, Gmail, Outlook e IMAP en una sola API.
ES 
EN 
FR 
DE 
IT 
BR 
NL 
PL 
TR