LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Outlook
Calendario de Google
Únase a la comunidad Slack Índice
Capacidades y costo
Decide y construye
API de Telegram Bot vs API de Telegram
API de Telegram Bot vs. API de Telegram: ¿Cuál necesitas?
En API del bot de Telegram y el API de Telegram (también llamada la API de usuarios de Telegram, construida sobre MTProto) resuelven diferentes problemas. Una ejecuta una cuenta de bot a través de HTTP. La otra ejecuta una cuenta de usuario real a través de un protocolo binario que implementas tú mismo. Esta guía detalla dónde te bloquea cada una, punto final por punto final, y lo que realmente cuesta construir y mantener un cliente de la API de usuarios de Telegram en comparación con conectar una cuenta existente a través de Unipile.
// Bot API: bloqueado, el usuario nunca le envió mensajes al bot
const res = await bot.sendMessage(ID de usuario, "Hola");
// -> 403 Prohibido: el bot fue bloqueado por el usuario
o nunca inició una conversación
// API de usuario de Telegram a través de Unipile: funciona, es una cuenta real
// POST /v2/:account_id/chats/send
const chat = await unipile.chats.create({
account_id: cuentaDeTelegramId,
ids_de_usuario: [nombre de usuario],
text: "Hola"
});chat.status: "enviado"
Los dos modelos
API de Bot de Telegram vs API de Usuario de Telegram, en una tabla
Si ya sabes que Telegram tiene múltiples APIs y solo quieres saber cuál se aplica a tu proyecto, esta tabla te lleva a ello en diez segundos. Si todavía necesitas el panorama completo de las tres APIs de Telegram, lee la guía de inicio primero. Aquí, profundizamos un nivel más en los dos contra los que la gente realmente construye: la API de Bots y la API de Usuarios de Telegram.
| Criterios | API del bot de Telegram | API de usuario de Telegram (MTProto) |
|---|---|---|
| Lo que conecta | Una cuenta de bot, creada y propiedad de tu aplicación | Una cuenta de usuario real de Telegram, vinculada a un número de teléfono |
| Protocolo | HTTP estándar, solicitudes y respuestas JSON | MTProto, un protocolo binario personalizado que tú implementas |
| Credenciales | Un token de bot emitido por @BotFather | api_id + api_hash from my.telegram.org |
| Identidad en los chats | Muestra una insignia de "bot" visible, distinta a la de una persona | Indistininguible de una persona que usa la aplicación |
| Quién puede enviar mensajes a quién | El bot solo puede responder una vez que el usuario inicia el chat | La cuenta puede enviar mensajes a cualquier persona, como cualquier usuario de Telegram |
| Implementación típica | Cualquier cliente HTTP, SDK oficiales y de la comunidad | Telethon, Pyrogram, GramJS, TDLib o una cuenta vinculada a través de Unipile |
| Coste | Gratis para usar | De uso gratuito, solo costo de infraestructura autohospedada |
API del bot de Telegram
ConectaUna cuenta de bot
ProtocoloHTTP, JSON
CredencialesToken del bot (BotFather)
IdentidadInsignia de bot visible
A quién le puede enviar mensajesSolo los usuarios que escribieron primero
CosteGratis
API de usuario de Telegram (MTProto)
ConectaUna cuenta de usuario real
ProtocoloMTProto, binario
Credencialesapi_id + api_hash
IdentidadIndistinguible de una persona
A quién le puede enviar mensajesCualquiera, como un usuario normal
CosteGratuito, autohospedado, solo el costo
La pregunta que decide
¿A quién quieres escribirle primero?
Cualquier otra diferencia entre la API de bots de Telegram y la API de usuarios de Telegram es secundaria frente a esta. Responde a esto primero y el resto de esta guía se convierte en una lista de verificación, no en una decisión.
Un bot no puede iniciar una conversación con un usuario que nunca le ha enviado un mensaje primero.
Esta es una regla de la plataforma de Telegram, no una limitación de Unipile ni un error de la biblioteca. Una cuenta de bot solo puede responder dentro de un chat que el usuario ya haya abierto, o después de que el usuario toque un
Esta es una regla de la plataforma de Telegram, no una limitación de Unipile ni un error de la biblioteca. Una cuenta de bot solo puede responder dentro de un chat que el usuario ya haya abierto, o después de que el usuario toque un
t.me enlace profundo o se une a un grupo en el que está el bot. Si su caso de uso requiere comunicarse con alguien que aún no ha interactuado con su bot, la API de Bot no es una opción, sin importar qué marco o biblioteca se encuentre sobre ella. La API de Bot funciona
El usuario habla primero con tu bot
Bots de asistencia, herramientas basadas en comandos, suscripciones a notificaciones, chatbots vinculados desde tu producto. El usuario encuentra tu bot, inicia el chat y, a partir de ahí, todo es un intercambio normal que la Bot API maneja bien. API del bot bloqueada
Debes dar el primer paso
Prospección de ventas, contratación, mensajería de clientes vinculada a una lista de contactos existente, o cualquier flujo de trabajo en el que su producto inicie contacto con un usuario de Telegram. Esto requiere una cuenta de usuario real, lo que significa la API de usuario de Telegram (MTProto), no la API de Bots.Matriz de capacidades
Qué funciona realmente, extremo por extremo
Más allá de la diferencia en el titular, aquí es donde cada opción te bloquea en la práctica. "API de usuario de Telegram (sin procesar)" significa un cliente MTProto de creación propia con una biblioteca como Telethon, Pyrogram, GramJS o TDLib. "Unipile" significa la misma cuenta de usuario real, conectada sin escribir código MTProto tú mismo.
| Capacidad | API de bots | API de usuarios de Telegram (sin procesar) | Unipile |
|---|---|---|---|
| Iniciar un chat con un usuario que nunca ha enviado un mensaje primero | No | Sí, sujeto a la configuración de privacidad del usuario | Sí, la misma regla que cualquier cuenta de Telegram |
| Enviar y recibir mensajes de texto | Sí, en los chats de los que forma parte el bot | Sí | Sí |
| Leer el historial de mensajes de antes de que el bot se uniera | No | Sí | Sí |
| Lista de participantes del grupo, agregar, eliminar | Limitado a los propios permisos del bot | Sí, si lo construyes | Sí, getParticipantsList, addParticipant, removeParticipant |
| Administración de grupos: aprobar, promover, revocar | Sí, solo si el bot es administrador | Sí, si lo construyes | No se admite |
| Canales, comunidades, difusiones | Sí, si se añade como administrador | Sí | No se admite |
| Chats secretos | No aplicable | Sí, si lo construyes | No se admite |
| Adjuntos de contacto, ubicación, encuesta y evento | Sí | Sí | No se admite |
| Llamadas de voz y vídeo | No | Posible, alto esfuerzo de implementación | No se admite |
| Tema de chat, archivar, eliminación de chat | No aplicable | Sí, si lo construyes | No se admite |
| Identidad de la cuenta | Separar la identidad del bot, insignia visible | Identidad de usuario real, vinculada a un número de teléfono | Identidad de usuario real, tu cuenta existente |
| Gestión de sesiones y dispositivos | Basado en tokens, sin concepto de dispositivo | Tú mismo gestionas la clave de autenticación MTProto y la autenticación de dos factores (2FA) | Gestionado a través de la función Dispositivos propia de Telegram |
Iniciar un chat en frío
API de botsNo
API de usuario (sin procesar)Sí, dependiente de la privacidad
UnipileSí
Historial de mensajes antes de unirse
API de botsNo
API de usuario (sin procesar)Sí
UnipileSí
Participantes del grupo (obtener / añadir / eliminar)
API de botsLimitado a los permisos del bot
API de usuario (sin procesar)Sí, autoconstruido
UnipileSí, endpoints dedicados
Administración de grupos
API de botsSí, si el bot administrador
API de usuario (sin procesar)Sí, autoconstruido
UnipileNo se admite
Canales, comunidades, difusiones
API de botsSí, como administrador
API de usuario (sin procesar)Sí
UnipileNo se admite
Chats secretos
API de botsNo aplicable
API de usuario (sin procesar)Sí, autoconstruido
UnipileNo se admite
Adjuntos de contacto, ubicación, encuesta o evento
API de botsSí
API de usuario (sin procesar)Sí
UnipileNo se admite
Llamadas de voz y vídeo
API de botsNo
API de usuario (sin procesar)Posible, gran esfuerzo
UnipileNo se admite
Gestión de sesiones y dispositivos
API de botsBasado en tokens
API de usuario (sin procesar)Clave de autenticación autogestionada + 2FA
UnipileLa función Dispositivos propia de Telegram
Lo que Unipile no cubre en Telegram
Canales, comunidades y difusiones, tema de chat, chats secretos, contactos, ubicación, archivos adjuntos de encuestas y eventos, administración de grupos (aprobar, promover, revocar), eliminación de chats, archivo, y llamadas de voz o video. Si tu proyecto necesita alguno de estos, solo un cliente de la API de usuario de Telegram de fabricación propia cubre toda la superficie.
Canales, comunidades y difusiones, tema de chat, chats secretos, contactos, ubicación, archivos adjuntos de encuestas y eventos, administración de grupos (aprobar, promover, revocar), eliminación de chats, archivo, y llamadas de voz o video. Si tu proyecto necesita alguno de estos, solo un cliente de la API de usuario de Telegram de fabricación propia cubre toda la superficie.
El costo real
El costo real de construir en MTProto
La API de usuarios de Telegram es gratuita, pero "gratis" solo cubre la licencia. Construir y mantener por cuenta propia un cliente de la API de usuarios de Telegram conlleva un coste de ingeniería real que una integración con la API de bots nunca tiene. Así es como se ve realmente ese coste.
01
Gestión de sesiones y claves de autenticación
MTProto es un protocolo binario, no REST. Tú implementas el esquema TL, el intercambio de claves de autenticación y persistes la sesión resultante por tu cuenta. Pierdes la sesión y el usuario tiene que volver a autenticarse desde cero. 02
Autenticación de dos factores
Las cuentas con contraseña en la nube requieren gestionar el flujo de autenticación de doble factor (2FA) basado en SRP de Telegram durante el inicio de sesión. Es una máquina de estados más que construir, probar y mantener funcional ante cada actualización del protocolo de Telegram. 03
Un api_id por número de teléfono
api_id y api_hash se emiten en my.telegram.org bajo "herramientas de desarrollo de API", y requieren una cuenta de Telegram activa. Telegram permite una sola api_id por número de teléfono, lo que da forma a cómo aprovisiona las credenciales de prueba y de producción. 04
Cuentas bajo observación automática
Telegram somete a los clientes no oficiales a observación automática. El envío masivo de mensajes (flooding), el spam y la inflación artificial de contadores pueden provocar un baneo permanente, lo que significa que la limitación de tasa (rate limiting) y el calentamiento (warm-up) son responsabilidad tuya, no una configuración predeterminada de la biblioteca.// Copiando y pegando un api_id de muestra de un repositorio de código abierto
// en lugar de registrar el tuyo en my.telegram.org
Error: API_ID_PUBLISHED_FLOOD
// Marcas de Telegram para valores de api_id publicados en código público.
Cada aplicación que envíes necesita su propio api_id / api_hash,
// uno por número de teléfono, o sus usuarios finales se encontrarán con este error.La tercera vía
Conectar una cuenta existente, omitir la compilación de MTProto
La mayoría de los equipos en realidad no quieren construir un cliente de Telegram. Quieren las capacidades de una cuenta de usuario real: iniciar conversaciones, leer el historial completo, gestionar los participantes de grupos, sin poseer una implementación de protocolo binario. Eso es lo que ofrece Unipile API de Telegram es para.
Conéctese a través de la función Dispositivos propia de Telegram
Unipile vincula una cuenta de usuario de Telegram existente a través de la función de Dispositivos de Telegram, el mismo mecanismo que le permite iniciar sesión en Telegram Desktop o Telegram Web. El inicio de sesión se realiza mediante código QR, o a través de Hosted Auth con
Unipile vincula una cuenta de usuario de Telegram existente a través de la función de Dispositivos de Telegram, el mismo mecanismo que le permite iniciar sesión en Telegram Desktop o Telegram Web. El inicio de sesión se realiza mediante código QR, o a través de Hosted Auth con
proveedores: "TELEGRAM" para un flujo de conexión instantánea. Sin api_id, sin api_hash, sin MTProto que escribir
Nunca gestionas el intercambio de claves de autenticación, el esquema TL ni la autenticación de dos factores (2FA) por ti mismo. La cuenta vinculada se comporta como un usuario real de Telegram porque lo es, no un bot ni un cliente simulado.
Nunca gestionas el intercambio de claves de autenticación, el esquema TL ni la autenticación de dos factores (2FA) por ti mismo. La cuenta vinculada se comporta como un usuario real de Telegram porque lo es, no un bot ni un cliente simulado.
Participantes del grupo, a través de puntos de enlace dedicados
obtenerListaDeParticipantes, agregarParticipante, eliminarParticipante, expuesto a través de POST, GETy DELETE /v2/{account_id}/chats/{chat_id}/participants. No hay llamadas personalizadas a MTProto que escribir para la gestión de membresía básica. Estado de la sesión vinculado a la lista de dispositivos de Telegram
Si el dispositivo Unipile se elimina de las sesiones activas de la cuenta dentro de Telegram, el estado de la cuenta cambia a
Si el dispositivo Unipile se elimina de las sesiones activas de la cuenta dentro de Telegram, el estado de la cuenta cambia a
desconectado. El ciclo de vida de la sesión es visible y predecible, no una caja negra que depuras solo. // Conectar una cuenta de usuario de Telegram existente
// mediante Hosted Auth, no se requiere código MTProto
const enlace = await unipile.autenticación alojada.create({
proveedores: ["TELEGRAMA"],
expiraEn: "2026-12-31T23:59:59.000Z"
});
// El usuario escanea el código QR con la aplicación de Telegram
// El estado de la cuenta se convierte en "conectado"
// GET /v2/{account_id}/chats/{chat_id}/participants
const miembros = await unipile.chats.obtenerListaDeParticipantes(ID de chat);account.status: "conectado"
Las mismas reglas, sin atajos para evitarlas
Una cuenta vinculada sigue siendo una cuenta de Telegram y sigue los propios límites de Telegram: evita cuentas totalmente nuevas para un uso intensivo, aumenta el volumen progresivamente y mantén al menos de 10 a 20 segundos entre mensajes. Consulta el Guía de la API de Telegram y el guía para enviar mensajes para la configuración completa.
Una cuenta vinculada sigue siendo una cuenta de Telegram y sigue los propios límites de Telegram: evita cuentas totalmente nuevas para un uso intensivo, aumenta el volumen progresivamente y mantén al menos de 10 a 20 segundos entre mensajes. Consulta el Guía de la API de Telegram y el guía para enviar mensajes para la configuración completa.
Árbol de decisión
Cuál es el adecuado para tu caso
Tres preguntas, en orden. Detente en la primera que coincida con tu proyecto.
1
¿El usuario siempre te envía mensajes primero y el bot solo necesita responder a comandos y mensajes?
->Bots de asistencia, notificaciones voluntarias, herramientas de comandos donde el usuario inicia el contacto.API de bots
2
¿Necesita comunicarse primero y también necesita canales, chats secretos, administración de grupos o llamadas?
->Cobertura completa de la plataforma, y estás dispuesto a construir y mantener tu propio cliente MTProto con Telethon, Pyrogram, GramJS o TDLib.API de usuario de Telegram, de creación propia
3
¿Necesitas contactar primero, actuar como una cuenta real y ponerte en marcha sin ser dueño de MTProto?
->Mensajería, historial de chat y gestión de participantes de grupos en una cuenta de usuario conectada, con la sesión gestionada por ti.Unipile
La mayoría de los equipos llegan aquí
Conecta una cuenta real de Telegram sin construir un cliente
Si tu proyecto necesita iniciar el contacto pero no requiere canales, chats secretos o llamadas, una cuenta vinculada a través de Unipile te permite lograrlo sin necesidad de mantener una implementación de la API de usuario de Telegram.
Constrúyelo con Unipile Conecta una cuenta real de Telegram sin construir un cliente
Si tu proyecto necesita iniciar el contacto pero no requiere canales, chats secretos o llamadas, una cuenta vinculada a través de Unipile te permite lograrlo sin necesidad de mantener una implementación de la API de usuario de Telegram.
Telegram Bot API vs Telegram API - FAQ
Preguntas frecuentes sobre cómo elegir entre la API de bots de Telegram y la API de usuario de Telegram (MTProto).
La Bot API es una interfaz HTTP que controla una cuenta de bot y expone una superficie deliberadamente limitada. La API de Telegram, también llamada API de Cliente, utiliza el protocolo binario MTProto y controla una cuenta de usuario real con el conjunto completo de funciones. Son tipos de cuenta diferentes, no dos versiones de la misma cosa.
Pregunta a quién necesitas escribir. Si tus usuarios te escriben primero y la identidad de un bot es aceptable, usa la API de Bot. Si necesitas comunicarte con personas que no te han contactado, o actuar como una persona real, necesitas acceso a la cuenta de usuario.
No. El usuario debe iniciar la conversación primero. Este es el único límite que aleja a la mayoría de los productos de la API de Bots, y ningún endpoint lo soluciona.
No. La API de bots solo necesita el token del bot que te da BotFather. api_id y api_hash provienen de my.telegram.org y son para la API de clientes, permitiéndose un api_id por número de teléfono.
Lo suficientemente difícil como para que casi nadie lo escriba desde cero. Te encargas de la persistencia de la sesión, la autenticación de doble factor, la reconexión y un protocolo binario. La mayoría de los equipos usan Telethon, Pyrogram, GramJS o TDLib, y aun así se hacen cargo del ciclo de vida de la sesión.
Es otro nombre para la API de cliente, la interfaz MTProto que se autentica como un usuario real de Telegram en lugar de como un bot.
Sí. Conectar una cuenta existente a través de la función de Dispositivos de Telegram otorga acceso a la cuenta del usuario sin implementar MTProto. Así es como Unipile vincula las cuentas de Telegram, mediante un inicio de sesión con código QR o un flujo de autenticación alojado.
¿Aún tiene preguntas? Nuestro equipo está aquí para ayudarle.
ES 
EN 
FR 
DE 
IT 
BR 
NL 
PL 
TR