API de Pabal

API de Pabal (MTProto)

Para crear un cliente que se conecte al servidor igual que la aplicación: datos de conexión, clave pública del servidor, flujo de inicio de sesión, actualizaciones y alcance del soporte.

La aplicación Pabal se comunica con el servidor mediante MTProto 2.0. Consulta este documento si vas a crear un programa que se conecte de la misma manera: otra aplicación, una automatización que funcione con una cuenta de persona o un cliente para investigación. Si lo que vas a crear es un bot, te basta con la Bot API, que es más sencilla.

Datos de conexión

Todavía no hay transporte HTTP, transporte WebSocket ni MTProxy. El reloj del dispositivo cliente debe estar en hora: los números de los mensajes MTProto se derivan de la hora, así que si el reloj va muy desviado, el servidor descarta los mensajes.

Clave pública del servidor

La primera vez que se conecta, un cliente MTProto cifra el intercambio de la clave de autorización con la clave pública RSA del servidor. Los clientes de Telegram llevan incorporada la clave pública de Telegram, así que para conectarse a Pabal hay que incorporar esta clave en su lugar (o además). Esta clave impide que otro servidor se haga pasar por el servidor Pabal.

-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEA4hH74xPQsUwr/pyXPdF4tVicYr6QbfeDrKC7mUOVrPLSL4FtmgGn
w+O4u6lVvOf3Udd1KY6+OL4fUZdMBlLzwsoGLoniiVR09dnvyXHE8LhQSS+i1LmI
oJbhQwXplLnUJf272fLXkD23e7ppKLkjYk+jeYObueCy5HYMSThklVeXEzbZVGZv
47o/mjU2vyFoRpa6wCIE4rpj1UIPtOMpekMI/TocIlGVJ+ch6cAVNxIDro53a1eG
/1oZRLQH4oViEGxeMMjBMY5gk5HPkZvjbqy4h8TjXEz7O5o0BRsSqG/OPtP/dRQV
X4ewPhj2WCU4e6l5X59ZKIcv4sQLOwClqQIDAQAB
-----END RSA PUBLIC KEY-----

curl -s -o server-key.pem https://pabal.me/docs/server-key.pem

Esta clave se genera una sola vez, la primera vez que arranca el servidor, y no cambia. Comprueba que el valor de Loaded RSA key … (fingerprint …) en el log del servidor coincide con el fingerprint de arriba.

Conectarse con Telethon

Este es un ejemplo en el que, con Telethon para Python, se inicia sesión con una cuenta de persona y se intercambian mensajes. Regístrate antes en la aplicación (ver más abajo).

# pabal_client.py — pip install telethon==1.42.0
# En la misma carpeta, server-key.pem (la clave pública del servidor descargada arriba)
import asyncio

from telethon import TelegramClient, events
from telethon.crypto import rsa

rsa.add_key(open("server-key.pem").read(), old=False)          # clave pública del servidor Pabal

client = TelegramClient("pabal", api_id=1, api_hash="0" * 32)  # la sesión se guarda en pabal.session
client.session.set_dc(2, "122.34.175.215", 8443)


@client.on(events.NewMessage(incoming=True))
async def show(event):
    sender = await event.get_sender()
    print(f"{sender.first_name}: {event.raw_text}")


async def main():
    await client.start(phone=lambda: input("Número de teléfono (+8210…): "))   # la primera vez, introduce el código
    me = await client.get_me()
    print(f"Sesión iniciada: {me.first_name} (id {me.id})")
    await client.send_message("BotFather", "/help")
    await client.run_until_disconnected()


asyncio.run(main())

• Usa Telethon 1.42, que es la versión que habla la capa 216. Las versiones más recientes intentan leer las respuestas con una capa superior y fallan con TypeNotFoundError.
• Telethon tiene bloqueado el registro de cuentas nuevas (sign_up()). Regístrate en la aplicación o llama directamente a auth.signUp.
• La sesión se guarda en el archivo pabal.session, así que las siguientes veces no se pide el código. Ese archivo es la llave de la cuenta: protégelo.

Flujo de inicio de sesión

Recibir actualizaciones

• En tiempo real: mientras la conexión está abierta, el servidor envía al instante los mensajes nuevos, las ediciones y los borrados como updateShortMessage y updates. La sesión que envió la petición recibe el resultado como respuesta RPC, así que no le llega lo mismo otra vez como push.
• pts: los cambios de cada usuario llevan un número de orden (pts). Si el cliente ve un hueco en los pts recibidos, es que se ha perdido algo.
• Ponerse al día: guarda el pts actual con updates.getState y, al volver a conectarte, obtén con updates.getDifference(pts, date, qts) los mensajes nuevos y los borrados de ese intervalo, junto con los usuarios y grupos relacionados. Si el pts que tiene el cliente va por delante del servidor (por ejemplo, si se reiniciaron los datos del servidor), llega differenceTooLong: vuelve a cargar la lista de chats.
• Bibliotecas como Telethon se encargan de todo este proceso por sí solas.

IDs y peers

Guarda el access_hash tal como te lo da el servidor y úsalo después (llega junto con la resolución de nombres de usuario, la lista de chats y las actualizaciones).

Archivos

• Subir: sube los fragmentos con upload.saveFilePart y haz referencia a ellos con inputFileUploaded…. Todavía no existe upload.saveBigFilePart para archivos grandes, así que en la práctica el límite es de 10 MB.
• Enviar: messages.sendMedia con inputMediaUploadedPhoto (foto nueva) o inputMediaPhoto (foto que ya está en el servidor). Otros tipos de contenido multimedia devuelven MEDIA_INVALID.
• Recibir: upload.getFile con inputPhotoFileLocation (foto de un mensaje) o inputPeerPhotoFileLocation (foto de perfil). Como máximo 1 MB por llamada.
• Fotos de perfil: photos.uploadProfilePhoto, photos.updateProfilePhoto, photos.getUserPhotos, photos.deletePhotos.
• Las fotos se guardan en un único tamaño, el original (no se generan miniaturas aparte).

Alcance del soporte

El servidor tiene manejadores para 408 métodos de la capa 216 y todos pueden leer las peticiones, pero los que se han comprobado de principio a fin con clientes reales son los métodos de abajo. El resto responde con el formato correcto, pero puede que el contenido llegue vacío o que no se registre.

También se ha comprobado que la aplicación oficial Telegram Desktop 6.2.6 funciona sin modificaciones en el registro, el inicio de sesión, los chats, las fotos, los grupos y la reconexión. El formato de las respuestas de los aproximadamente 60 métodos a los que llama la aplicación al arrancar se verifica aparte.

Errores

Los errores llegan como el rpc_error estándar (error_code + error_message). error_message siempre tiene la forma de mayúsculas, números y guiones bajos (PEER_ID_INVALID) y, si hace falta, lleva detrás : descripción.

Lo que todavía no existe

• Canales y supergrupos (channels.* responde, pero no se muestra bien en la aplicación), chats secretos, llamadas
• Contenido multimedia distinto de las fotos, upload.saveBigFilePart, miniaturas
• Verificación en dos pasos (SRP): no se puede configurar, y las operaciones que la requieren se rechazan
• Transportes HTTP y WebSocket, MTProxy, envío de msgs_ack, sustitución de bad_server_salt
• Repartir la carga entre varios servidores: un solo servidor atiende todos los DC del 1 al 5

Para conectar la aplicación oficial de Telegram a Pabal

La aplicación de Telegram incorpora la dirección del servidor y la clave pública al compilarse. Por eso no se cambia desde la pantalla de ajustes: hay que modificar el código fuente y volver a compilarla. Así es como se hizo la aplicación Pabal (Pabal.app). Si operas un servidor, consulta Instalar el servidor — conectar la aplicación.