Telegram: Cuenta personal
Telegram: Lee conversaciones, encuentra acuerdos, reúne documentos y prepara respuestas con tu mensajero conectado.
Reúne contexto para decidir: qué cambió, qué materiales necesitas y a quién responder. Elige una tarea, sustituye los chats y envía la petición. Primeras tareas ofrece un inicio breve; aquí se combinan varios mensajes.
Qué cambió durante mi ausencia
Usa tg CLI. No he leído el grupo de trabajo en tres días. Compara los últimos acuerdos con los anteriores: plazos, alcance y responsables. Muestra cambios, desacuerdos y mensajes de origen. No envíes nada.Recibirás una lista antes → después. Por ejemplo: el plazo pasó del viernes al lunes; la fecha se confirmó, pero el nuevo responsable solo se propuso.
Reunir materiales para una reunión
Usa tg CLI. Busca los materiales de la reunión de mañana en el grupo de trabajo y mi conversación con Anna: presentación actual, presupuesto y preguntas abiertas. Muestra el último mensaje de aprobación de cada archivo. Primero lista los archivos; no descargues ni envíes nada.Recibirás las versiones aprobadas y preguntas para la agenda. Después pide guardar archivos concretos en la carpeta que elijas.
Entender una conversación larga
Usa tg CLI. Busca la conversación sobre la excursión del último mes en el grupo de padres. Reúne fecha, lugar, coste y cosas que llevar. Separa decisiones confirmadas de propuestas y muestra fuentes. No envíes nada.Recibirás una lista práctica en lugar de decenas de mensajes. Si se habló del lugar sin elegirlo, seguirá siendo una pregunta abierta.
Comprobar compromisos antes de responder
Usa tg CLI. Antes de responder al contratista, revisa nuestro chat privado y el grupo de reforma de las últimas dos semanas. ¿Qué prometimos, qué está hecho y qué falta aclarar? Prepara una respuesta con acuerdos que la respalden. Muestra el borrador sin enviarlo.Recibirás compromisos comprobables y un borrador con contexto de ambos chats. Fechas y promesas sin confirmar seguirán siendo preguntas.
Comandos e instrucciones
tg le permite a usted, o a su agente de IA, leer y escribir su propia cuenta de Telegram desde la terminal. Esta página es el recorrido: desde el primer inicio de sesión hasta la lectura, envío y ejecución de grupos, en el orden en que lo necesitará. Ábrelo cuando empieces con tg, o cuando quieras saber qué es posible antes de preguntarle a tu agente.
Después de leerlo, sabrás cómo nombrar un chat, cómo leer y buscar sin que nadie vea que miraste, cómo enviar de forma segura y cómo obtener respuestas que un script puede usar. Cada comando y opción se encuentra en la referencia de comando; esta página explica cómo encajan.
Términos utilizados en esta página:
- Perfil: una cuenta de Telegram configurada en esta computadora, con su propio inicio de sesión y configuración. La primera palabra de un comando la selecciona (perfiles).
- Chat: cualquier conversación: un chat individual, un grupo, un canal o Mensajes guardados.
- Almacén local: la base de datos de esta computadora donde tg guarda cada mensaje que lee (el almacén local).
- Control de envío: comprueba cada envío aprobado: un perfil de solo lectura, la lista de destinatarios permitidos y un límite por hora (el control de envío).
Cada comando realiza una tarea, imprime la respuesta y termina. Solo tg personal watch, tg personal serve y tg personal mcp serve permanecen activos, y cada uno lo indica.
Esto es una plantilla de sintaxis, no un comando para copiar. Sustituye los marcadores por los valores de los ejemplos siguientes.
tg [profile] [options] <resource> <action> [arguments]Qué puedes hacer
Lee un chat con tu agente
Con la cuenta conectada, pide un resumen breve. Esta tarea lee mensajes y no envía nada.
Tu petición:
Usa tg CLI. Resume los cinco últimos mensajes de Book club. Muestra decisiones y preguntas pendientes. No envíes nada.
Comando:
tg personal messages list "Book club" --limit 5 --jsonEjemplo de respuesta del agente:
Decisión: la próxima reunión será el jueves a las 18:00.
Pendiente: dónde reunirse.
Puedo mostrar los mensajes que sustentan el resumen. No se ha enviado nada.
El resumen anterior es ficticio. Pídale al agente que abra los mensajes fuente antes de confiar en su interpretación. La configuración, las acciones de mensajes y los permisos se explican en las secciones siguientes.
Primeros pasos
npm install -g @wirecat/tg-clitg skill install --for all # the agent skilltg personal setup # guided app registration, login and agent skilltg personal chats list --limit 5 # your newest chatstg personal messages list me # Saved Messages, the latest 20Espere unos cinco minutos para la configuración. Las descargas del historial son independientes: elige un chat y una cantidad de mensajes antes de tg personal messages sync <chat> --last 100. Un agente puede leer tg skill show sin iniciar sesión; tg personal setup --agent codex selecciona explícitamente la skill para un agente. tg setup --help explica las banderas. No hace falta nada más para leer.
Para consultar los argumentos de una tarea, usa tg commands search messages --json para
un comando o tg commands messages --json para un grupo. Ambos incluyen las opciones globales
y los códigos de salida. Consulta cada ruta de comando en una llamada separada;
tg commands --json devuelve todo el árbol.
Iniciar sesión
tg personal setup es el comando para el primer uso. Por defecto registra la aplicación automáticamente y usa un QR; --app browser y --method phone eligen los otros métodos. Para iniciar sesión sin los demás pasos, o terminar un acceso interrumpido o caducado:
tg personal session start # QR code: Settings → Devices → Link Desktop Devicetg personal session start phone # phone number, the code Telegram sends, your 2FA passwordtg personal session start phone --sms # the same, asking for the code by SMS instead of in the apptg personal session start qr # without a terminal (an agent): the QR code as text to paste into the chatEl primer inicio de sesión también solicita su propia aplicación Telegram desde my.telegram.org; --app auto completa el sitio por usted. Ambos pasos, y qué se guarda dónde: login, sesiones y perfiles.
Los secretos nunca se introducen como argumentos. El hash de la aplicación y la contraseña 2FA se solicitan sin mostrarlos; el código y el teléfono se solicitan o se leen por stdin. Los argumentos son visibles para todos los procesos mediante ps y quedan en el historial de la terminal.
Para CI, TG_API_ID y TG_API_HASH proporcionan la aplicación sin usar el llavero y tienen prioridad sobre él.
tg personal account show # who this profile is logged in as, with the phone number
tg personal account show --hide-phone # the same without the phone numbertg account list # every profile on this computer and the account each is logged in astg personal account sessions list # every device and app logged in to the account; ends nothingtg personal session end # log out on Telegram's side, and delete the session heresession end también cierra la sesión en Telegram: el dispositivo desaparece de la lista de la aplicación. Para cerrarla desde otro dispositivo, usa Ajustes → Dispositivos.
Perfiles: la primera palabra
Puedes utilizar varias cuentas. El perfil es la primera palabra, no una opción:
tg personal chats list # profile "personal"tg work chats list # profile "work"
export TG_PROFILE=work # or for a whole shell sessionLa primera palabra es el perfil si no es un comando. Por eso un perfil no puede llamarse chats: el nombre se rechaza con una explicación. Los nombres admiten letras, cifras, puntos, guiones y guiones bajos.
Cada perfil tiene su propia sesión, su propia aplicación, su propia configuración y su propia lista de destinatarios permitidos. TG_PROFILE_LOCK fija un proceso a un perfil, por lo que un agente no puede elegir uno con menos límites (perfiles).
Cómo indicar un chat
Cuando un comando acepta <chat>, puedes usar:
- Un título completo o parcial:
"Book club",book. - Un identificador:
-1001234567890. - Un nombre de usuario:
@example_channel. mepara Mensajes guardados.
Si el título coincide con varios chats, el error muestra los candidatos y sus identificadores. tg nunca adivina: un mensaje enviado a la conversación equivocada no se puede deshacer. Repite con el identificador. Este no cambia, así que úsalo una vez que lo tengas.
messages show y messages context también aceptan un localizador msg: en lugar del chat e identificador, como el que devuelve search messages --json en cada resultado.
Una persona (<person> en contacts show) puede indicarse por identificador, @username o parte de su nombre.
Leer
Leer no marca como leído. Ningún comando siguiente muestra a otros que has mirado. Solo lo hace tg personal chats mark-read (más abajo).
Chats
tg personal chats list # newest first, archived chats includedtg personal chats list 'unread_count>0 kind:group' --offline # only groups with unread messagestg personal chats list 'title:*book*' --offline # titles containing "book"; at least 3 characterstg personal chats show "Book club" # kind, unread count, last message, who is in itUna consulta de chats se responde desde el archivo local, así que necesita --offline: Telegram no filtra nada en línea. kind: acepta dialog (individual), group, channel o saved. Los grupos y canales tienen su propia sección.
Mensajes
tg personal messages list "Book club" # the latest 20, oldest firsttg personal messages list "Book club" --limit 50tg personal messages list "Hiking" topic:12 # one forum topic; topics list shows the idstg personal messages show "Book club" 4242 # one messagetg personal messages context "Book club" 4242 # it, and 5 messages either sidetg personal messages context "Book club" 4242 --before-n 2 --after-n 10En context, el mensaje consultado se marca con ◀ en la terminal y "anchor": true en JSON.
topic:<id> en la consulta lee hacia atrás desde el mensaje más reciente del tema o desde id<…. Se rechaza el tema General (1): Telegram no asigna un ID de tema a sus mensajes, así que lee el chat completo. Con --offline, topic: selecciona los mensajes guardados de ese tema.
Enlaces a mensajes
tg personal messages link <chat> <message> o tg personal messages link <msg:locator> devuelve { item: { ref, url, access, reason } }. Los enlaces permanentes de canales y supergrupos pueden ser públicos o restringidos; un enlace no otorga membresía. Los diálogos, grupos básicos y mensajes guardados devuelven un localizador. Sin conexión valida el objetivo almacenado y no devuelve ningún enlace permanente. Se rechaza un localizador para otra cuenta. Este comando singular difiere de messages links, que explica las relaciones de conversación (búsqueda de tema).
Qué necesita respuesta
tg personal inbox # other people's unread messages, in every chattg personal inbox 'date>2h' # everything that came in during the last two hourstg personal inbox --new # what arrived since the last --new — for scheduled runstg personal inbox --new --jsonl # the same for a script: one message per lineinbox muestra mensajes de otras personas, nunca los tuyos, indicando su chat. Omite chats silenciados y archivados salvo que te mencionen o respondan; --all los incluye. Por stderr indica cuántos omitió.
inbox --new mueve un punto guardado. El siguiente --new empieza donde terminó este, de modo que cada mensaje se muestra una vez. El primer --new mira 24 horas atrás. inbox sin --new e inbox 'date>…' no mueven el punto. inbox normal devuelve lo mismo hasta que los mensajes se lean en la aplicación, ya que no marca nada como leído.
Cada ejecución lee como máximo 20 chats. Los demás forman una entrada de missing, con el paso para consultar uno. Si un chat tiene más de --limit pendientes, muestra los más recientes e indica por stderr cómo leer el resto.
Compromisos pendientes: review
tg personal review # the last 3 daystg personal review 'date>"2026-09-23T09:00:00+02:00"' # from where the last review endedtg personal review 'chat:"Book club"' --jsonMuestra todos los mensajes —tuyos y ajenos— en los chats con actividad desde el date> de la consulta. Sirve para revisar qué prometiste, qué esperas de otros y qué falta aclarar; clasificarlos corresponde a ti o al agente. No marca como leído.
El primer paso next de la respuesta, review.next, es la siguiente revisión: empieza donde terminó esta (date>"<until>"). Ejecuta la siguiente revisión desde ese paso para no dejar huecos. Si la revisión está incompleta —demasiados chats o un chat limitado a los 300 mensajes más recientes— lo avisa; conviene no adelantar el punto de inicio. Lee como máximo 20 chats por ejecución.
Preguntas sin respuesta
tg personal review --unanswered # questions nobody answered in 24 hourstg personal review 'chat:Neighbours' --unanswered 4h--unanswered [duration] conserva solo preguntas pendientes para ti o los administradores. Una pregunta contiene ? (no cuenta dentro de enlaces) o responde a ti o a un administrador. Se considera contestada si tú o un administrador respondéis o sois los siguientes en hablar tras quien preguntó. Omite preguntas más recientes que el intervalo indicado (24 horas por defecto) para dar tiempo a responder. Si no se conocen los administradores, lo avisa y solo cuenta tus respuestas. Usa una duración como 4h o 1d; no se admite un número de horas sin unidad.
Las transcripciones de voz guardadas también cuentan en este filtro. Agregue --transcribe para transcribir mensajes de voz que no tengan una transcripción guardada antes de seleccionar las preguntas. Un mensaje de voz que no se pudo transcribir mantiene la revisión incompleta: un resultado vacío no prueba que no haya preguntas sin respuesta. Mantenga el límite anterior mientras la respuesta tenga una entrada en missing.
Mensajes de voz
tg personal messages transcribe "Book club" 4242 # by Telegram where it can, else a model heretg personal messages transcribe "Book club" 4242 --local # only the model on this machinetg personal messages list "Book club" --transcribe # every voice message shown that has no text yettg personal inbox --transcribetg personal review --transcribetg personal messages list "Book club" --transcribe --model gigaam-v3La transcripción local requiere una grabación Ogg Opus completa, mono o estéreo, sin un límite fijo de diez minutos. Las grabaciones más largas necesitan más memoria y tiempo de procesamiento.
Telegram transcribe para cuentas Premium y algunos mensajes semanales con su prueba gratuita. Si no está disponible, lo hace un modelo local y la grabación no sale del equipo. El modelo se descarga una vez, solo cuando lo pides:
tg personal models list kind:audio # the models, which is downloaded, which is the defaulttg personal models download parakeet-v3 # once, checked against the sha256 this version expects| Modelo | Idiomas | Tamaño |
|---|---|---|
parakeet-v3: predeterminado | 25: búlgaro, checo, danés, alemán, griego, inglés, español, estonio, finés, francés, croata, húngaro, italiano, lituano, letón, maltés, neerlandés, polaco, portugués, rumano, ruso, eslovaco, esloveno, sueco y ucraniano | 670 MB |
gigaam-v3 | ruso; el mejor de los tres para ruso | 232 MB |
gigaam-v3-ctc | ruso; algo más rápido, con peor uso de mayúsculas | 225 MB |
--model elige otro modelo para un comando, al lado de --transcribe o en messages transcribe; transcribe_with y speech_model en la configuración eligen los valores predeterminados (configuración). Una transcripción se guarda en el archivo local y se reutiliza en listas de mensajes, bandejas de entrada y revisiones. Llamar nuevamente a messages transcribe puede solicitar una nueva transcripción o ejecutar el reconocimiento nuevamente. --transcribe puede tardar unos minutos.
Archivos
tg personal messages download "Book club" 4242 --output-dir ~/Downloads # one message's filestg personal messages download "Book club" --all --output-dir ~/tg-files # every file of the chat, newest firstSe guardan fotos, archivos, vídeos y notas de voz; la carpeta se crea si falta. Un archivo mantiene su propio nombre; uno sin nombre recibe la identificación del mensaje. Una descarga nunca sobrescribe un archivo. Con --all, un nombre ya tomado recibe la identificación del mensaje al frente. --all recuerda dónde se detuvo en un pequeño archivo al lado de las descargas y el mismo comando continúa desde allí. Sólo usted puede leer los archivos guardados. Envío de archivos, formatos y texto de búsqueda: archivos adjuntos.
Personas
tg personal contacts list # people you have a one-to-one chat with, newest firsttg personal contacts list 'name:*ann*' --order nametg personal contacts show @example_user # their bio and the chats you sharetg personal contacts lookup # who has a phone number — asks for it, or reads it from stdintg personal contacts sync # your whole Telegram contact list into the local storetg personal contacts show @example_user # flags, last seen, registered, messages per shared chattg personal contacts context @example_user --chat "Book club" # their latest messages theretg personal contacts check @example_user # does the account look like a bot or a spammercontacts list son las personas con las que tienes una conversación individual. contacts sync también incluye el resto de tu lista de contactos de Telegram. name: y notes: buscan entre las personas que guarda el almacén local, así que antes necesitan un contacts sync (o mensajes ya leídos); si no hay nada guardado, la consulta se rechaza. notes: y search notes encuentran cualquier parte de una palabra, sin distinguir mayúsculas, también en el título; una consulta de uno o dos caracteres se rechaza ("search needs at least three characters"). contacts lookup nunca toma el número como argumento: introdúzcalo o escríbalo cuando se le solicite. El perfil de una persona, sus mensajes recientes, el bot check y lo que envía a dónde: personas.
Para cambiar contactos y tu perfil:
tg personal contacts add @example_user # under the name they showtg personal contacts rename @example_user Ann "from work" # a name only you seetg personal contacts remove @example_user # the chat staystg personal contacts block @example_user # they need not be a contacttg personal contacts unblock @example_usertg personal contacts import people.txt # one "number, name" per line; never numbers as argumentstg personal account update --first-name Ann --description "about me" --photo me.jpgtg personal account sessions end --others # logs out every other device, your phone too; asks firstcontacts import indica cuántos envió y a quién reconoció Telegram, nunca teléfonos. account sessions end pregunta antes de actuar; --yes aprueba en un script.
Páginas
Las listas muestran limit filas (20 por defecto). chats list, contacts list, chats members list y topics aceptan --page y --all:
tg personal contacts list --limit 5 # five a pagetg personal contacts list --limit 5 --page 2 # the sixth to the tenthtg personal contacts list --all # every row, no paging⚠ La paginación de una lista activa puede repetir u omitir filas. Los más recientes van primero; un mensaje entre la primera y segunda página puede cambiar quién aparece en cada una.
Los mensajes de un chat no usan números de página: aceptan una consulta sobre id y date, y --cursor para la página siguiente, que permiten continuar con precisión:
tg personal messages list "Book club" "id<4242" # older than message 4242tg personal messages list "Book club" "id>4242" # newer than 4242, oldest firsttg personal messages list "Book club" "date>2h" # what came in during the last two hourstg personal messages list "Book club" 'date>"2026-09-20T09:00:00+02:00"'tg personal messages list "Book club" "date<1d" # what came before this time yesterdayEn la terminal, las indicaciones para la página siguiente van por stderr; en JSON es el paso page.next, que da --cursor. id< e id> aceptan un identificador de mensaje. date> y date< aceptan ISO 8601 o un intervalo anterior: 30m, 2h, 1d. En messages context, --before-n y --after-n son cantidades de mensajes, porque el punto de referencia ya es el mensaje.
Encontrar un chat antes de escribir
tg personal chats list 'title:*book* kind:group' --offline # groups with "book" in the titletg personal contacts list 'name:*ann*' # people by name or @usernametg personal search all "contract" # messages and notes kept here, and Telegram's own searchtg personal search all "contract" --offline # only this computer; the query never leaves ittg personal search messages "contract" # the text of every message this machine has kepttg personal search messages 'contract chat:"Book club"'tg personal search messages 'body:/.*invoice.*(march|april).*/'Las búsquedas de chat y contactos necesitan al menos tres caracteres. search messages utiliza el lenguaje de consulta de búsqueda: invoice también encuentra otras formas de la palabra, invoic* busca comienzos y exact:invoice solo esa forma. Lee lo que serve obtuvo o guardó y también solicita la búsqueda propia de Telegram (--backend archive solo para el archivo local). body:/…/ compara una expresión regular con el mensaje completo. Más: búsqueda de mensajes. Una vez que tengas el chat, usa su id.
Enviar
No se envía nada a menos que hayas escrito un comando que envíe, y no pide confirmación: el chat y el texto ya están en la línea que escribiste. Cada envío pasa por el control de envío: un perfil de solo lectura, la lista allow del perfil, la lista de destinatarios permitidos y el límite por hora (el control de envío). Se registra cada intento, nunca su texto: tg personal sends list.
tg personal messages send me "a note to myself"tg personal messages send "Book club" "See you at 7" --silent # no notificationtg personal messages send "Book club" "a link, no card" --no-previewtg personal messages send "Book club" "**Bold** and _italic_" --md # Telegram Markdowntg personal messages send "Book club" "<b>Bold</b> and <i>italic</i>" --html--md utiliza el formateador de Telegram: **bold** o *bold*, _italic_, __underline__, ~~struck~~ o ~struck~, ||spoiler||, código en línea, código delimitado con un idioma, [label](https://example.com) y líneas de cita que comienzan con > . Los estilos pueden anidar; code/pre no puede anidarse con otras entidades, los enlaces no pueden anidarse y las comillas no pueden anidarse. Sin la bandera, el texto permanece como se escribió. La barra invertida escapa de una marca; Los _ y * internos de palabra permanecen literales. Las marcas en línea abiertas permanecen literales; Se rechaza una valla abierta. Los enlaces admiten URL absolutas http, https y mailto. messages edit y los subtítulos multimedia utilizan el mismo formateador. Telegram __text__ está subrayado; MAX __text__ está en negrita. Un solo *text* está en negrita en Telegram.
--html interpreta el texto como HTML de Telegram, el mismo que el de Bot API: <b>, <i>, <u>, <s>, <a href>, <code>, <pre language="…">, <blockquote> y <tg-spoiler>. Los saltos de línea y los espacios se mantienen tal como los escribes. Se rechaza un enlace de mención (tg://user?id=) o un emoji personalizado. --md y --html no se pueden combinar. messages edit también acepta --html.
Texto desde stdin
Si omites el texto, se lee por stdin. Es la única forma de enviar varias líneas y evita que aparezca en ps y en el historial:
printf 'first line\n\nthird line' | tg personal messages send me
tg personal messages send "Book club" < note.txtProgramar un envío
tg personal messages send "Book club" "Tomorrow" --at-time 2026-10-01T09:00 # local timetg personal messages send "Book club" "In two hours" --at-time 2h # or 30m, 1d from nowtg personal messages scheduled "Book club" # what waits to be sent there--at-time entrega el mensaje a Telegram, que lo enviará incluso con el equipo apagado. La hora se redondea hacia abajo al minuto. Rechaza plazos inferiores a un minuto o superiores a un año. El mensaje cuenta para el límite en la hora en que Telegram lo envía. Cancélalo o modifícalo en la aplicación de Telegram; tg no lo hace.
Archivos, fotos y voz
tg personal messages send "Book club" "The agenda" --file agenda.pdf # byte for byte; the text is the captiontg personal messages send "Book club" --photo picture.jpg # recompressed by Telegramtg personal messages send "Book club" --file trip.mp4 # a video plays in the chattg personal messages send "Book club" --file trip.mp4 --as-file # the same video as a file to downloadtg personal messages send "Book club" --voice note.ogg # a voice message, alone, with no texttg personal messages send "Book club" --file 3f9a.pdf --filename "Report Q3.pdf" # the name others seeRepite --photo o --file para enviar hasta diez adjuntos como un álbum. Las fotos y los vídeos pueden compartir álbum; los documentos deben ir en otro grupo. Los mensajes de voz se envían aparte. El pie corresponde al primer elemento y cada elemento cuenta para el límite horario. JSON incluye el primer message y la lista completa messages.
tg personal messages send "Book club" "Trip photos" --photo first.jpg --photo second.jpg--photo acepta .jpg, .png o .webp. Un .mp4 o .mov pasado con --file se envía como vídeo salvo que añadas --as-file. --voice acepta un archivo Ogg Opus (.ogg, .oga, .opus) y se envía solo: sin texto ni otro archivo. Los archivos y carpetas conocidos de credenciales, las carpetas de tg y el almacén local están protegidos. Las carpetas de trabajo ocultas normales están permitidas; --allow-any-file en la CLI permite usar rutas protegidas.
--spoiler difumina una foto o un vídeo hasta que se toca; un documento o un mensaje de voz no pueden aceptarlo. --caption-above muestra el texto encima de la foto o archivo. Solo los bots pueden proteger un mensaje para impedir que se reenvíe; Para proteger el contenido, active la configuración propia del chat en Telegram. Formatos, descargas y búsqueda de texto dentro de archivos: archivos adjuntos.
Responder a un mensaje
tg personal messages send "Book club" "Agreed" --reply-to 4242Una respuesta es un envío: admite todas sus opciones.
Reacciones y encuestas
tg personal reactions add "Book club" 4242 👍 # replaces the reaction you hadtg personal reactions remove "Book club" 4242tg personal reactions list "Book club" 4242 reaction:🔥 --limit 20 # who reacted, newest first; --cursor goes ontg personal polls show "Book club" 4250 # the poll and its answer idstg personal polls voters "Book club" 4250 'answers:<answer id>' # who chose it; not in an anonymous polltg personal polls vote "Book club" 4250 <answer id>tg personal polls vote "Book club" 4250 --retracttg personal polls create "Book club" "Which day?" Monday Tuesday --anonymoustg personal polls create "Book club" "Pizza now?" yes no --close-time 5m # closes by itself; 5s to 10mtg personal polls close "Book club" 4250 # your own poll; it cannot be reopenedtg personal polls create "Book club" "2+2?" 3 4 5 --quiz --correct 2 --solution "Four." # a quiz; a vote is finalAl leer un chat, las reacciones aparecen bajo el mensaje: 👍 3 🔥 1 (you: 🔥). reactions list nombra a quienes reaccionaron; Telegram lo rechaza en un canal y en un chat que oculta la lista, y el error dice cuál es el motivo (reactions.broadcast, reactions.list-hidden) en lugar de responder con una lista vacía. Votar en una encuesta pública muestra tu nombre a todos en el chat. Vota con los ID que imprime polls show, nunca por la posición de una respuesta. --multiple permite elegir varias respuestas. Solo se puede cambiar el voto en una encuesta creada con --revote. Se rechazan antes de enviar nada: votar en una encuesta cerrada, elegir dos respuestas en una de respuesta única, cambiar o retirar un voto definitivo y usar --retract sin haber votado; también se rechaza cerrar una encuesta ajena.
Bots y sus botones
Úsalo cuando un bot responde con botones bajo un mensaje, o cuando quieres iniciar un bot o abrir su mini app.
tg personal messages show "Shop bot" 4300 # the buttons are numbered under the messagetg personal messages press "Shop bot" 4300 2 # button 2, counted from 1 across the rows
tg personal messages press "Shop bot" 4300 "Order" # or by its exact texttg personal chats start "Shop bot" --start ref7 # the same as its Start button; the bot sees it
tg personal chats start "https://t.me/shop_bot?start=ref7" # a bot's link, even one you never opened
tg personal chats app "Shop bot" --start go # the address of its mini app, signed in as youEl bot ve que has pulsado un botón o lo has iniciado. press solo admite botones de callback. Un botón que pide tu contraseña 2FA, un enlace, un botón que envía tu número de teléfono o tu ubicación y uno que abre una mini app se rechazan antes de enviar nada. La dirección que imprime chats app te inicia sesión en la app del bot: no la compartas.
Editar, reenviar, fijar y eliminar
tg personal messages edit "Book club" 4242 "the corrected text" # your own message; --md or --html as in a sendtg personal messages forward "Book club" 4242 --to me # checked against the chat it goes totg personal messages forward "Book club" 4242 --to "Hiking" --topic 12 # into one topic of a forumtg personal messages pin "Book club" 4242 # quiet unless --notifytg personal messages unpin "Book club" 4242tg personal messages delete me 4242 4243 --allow-dangerous # at most 10, for you onlytg personal messages delete me 4242 --allow-dangerous --for-everyoneUna edición llega a personas que quizá ya leyeron el texto anterior. Un reenvío es un mensaje nuevo y pasa por la misma protección aplicada al chat de destino. Las eliminaciones no se pueden deshacer: por eso preguntan primero. Responde y o añade --allow-dangerous. En supergrupos y canales Telegram solo elimina para todos; allí solo funciona --for-everyone.
Qué cuenta para el límite por hora: un mensaje, un reenvío, una edición, una fijación con notificación, una nueva encuesta, el cierre de una encuesta y cada mensaje eliminado. No cuentan una reacción, un voto ni una fijación silenciosa.
Si no se conoce el resultado
El código 14 significa que la conexión se interrumpió después de salir el mensaje: puede haber llegado. El error incluye --operation-id. Repite con ese identificador para que Telegram descarte la segunda copia:
tg personal messages send "Book club" "See you at 7" --operation-id <id from the error>tg personal messages forward "Book club" 4242 --to me --operation-id <id from the error>Los reenvíos y encuestas también incluyen ese identificador. Repetir sin él envía otro mensaje. Un archivo se sube antes de enviar el mensaje: tg reintenta tres veces una subida interrumpida y, si aun así falla, el error dice que no se envió nada; ese comando puedes simplemente repetirlo. Es seguro repetir las ediciones y el orden de temas. Tras una creación de resultado desconocido, comprueba la lista de temas antes de crear de nuevo. Crear una carpeta no lo es: mira primero en tg personal chats folders list o puedes acabar con dos. Un envío con --at-time nunca se repite: consulta tg personal messages scheduled <chat>.
Tu lista de chats: archivar, fijar, marcar como no leído, silenciar
tg personal chats archive "Book club" # into the archive; `unarchive` brings it backtg personal chats pin "Book club" # to the top of your list; `unpin` lets it move downtg personal chats mark-unread "Book club" # the dot on your own devices; nobody sees ittg personal chats mute "Book club" --until 2h # without --until, for good; `unmute` hears it againEsto cambia solo tu propia lista y tus notificaciones; nadie en el chat lo sabe. Telegram rechaza un chat fijado más allá de su límite de chats fijados, y también se rechaza fijar uno en el archivo.
Marcar un chat como leído
tg personal chats mark-read "Book club" # up to the newest messagetg personal chats mark-read "Book club" --until-id 4242 # only up to this onetg personal chats mark-read "Hiking" --topic 12 # only this forum topictg personal messages list "Book club" # read without sending a receiptLa otra persona lo ve. Pasa por los controles como acción read y no cuenta para el límite por hora.
Carpetas
tg personal chats folders list # your folders, in the order the app shows themtg personal chats folders show "Trips" # one folder, with the names of its chatstg personal chats folders create "Trips" --chat "Hiking" --chat @katetg personal chats folders update "Trips" --title "Travel" --add "Climbing" --remove @katetg personal chats folders delete "Travel" # the chats staytg personal chats folders order "Travel" "Work" # these first; the rest keep their order after themtg personal chats folders join https://t.me/addlist/AbCdEf # a folder someone shared: joins every chat in ittg personal chats folders create "Inbox" --include contacts,groups --skip muted,archived --emoji 📥tg personal chats folders update "Inbox" --exclude-chat "Noisy group" --pin @katetg personal chats folders update "Inbox" --include none # no kinds any more; only the chats named in itUna carpeta puede incluir automáticamente contacts, non-contacts, groups, channels, bots con --include; --skip excluye muted, read, archived. --exclude-chat excluye un chat concreto y --pin lo fija arriba. Al update, --include y --skip sustituyen las reglas anteriores y --remove quita el chat de todas las listas. Una carpeta compartida por enlace no admite reglas. --emoji debe ser un icono de carpeta de Telegram: los demás se descartan sin error y la respuesta muestra lo realmente guardado.
Una carpeta se indica por su ID o su título exacto. Solo tú ves tus carpetas; cada cambio pasa igualmente por las comprobaciones como un cambio de account. join es distinto: las personas de esos chats ven que te has unido, como con tg personal chats join. «Todos los chats» mantiene su posición con order.
Comentarios de un canal
tg personal messages comments "Rozetked" 27644 # the comments under post 27644, oldest firsttg personal messages comments "Rozetked" 27644 "id<3732413"tg personal messages send "My channel" "Thanks!" --comment-to 120Los comentarios están en el grupo de discusión del canal: la respuesta lo identifica como discussion, y el comentario es una respuesta allí, por lo que la lista de destinatarios y el límite por hora lo contabilizan para ese grupo. Una publicación cuyo canal no tenga grupo de discusión o esté cerrada a comentarios termina con el código 6.
Publicar como un canal
En un grupo donde puedas publicar como uno de tus canales, consulta primero los remitentes disponibles y elige uno:
tg personal chats send-as "Book club"tg personal messages send "Book club" "Meeting moved to 8" --send-as <id from the list>La lista siempre te incluye, y default señala la opción guardada del grupo; leerla no cambia nada. Se rechaza un ID que no esté en la lista. --send-as también funciona con archivos, tg personal messages forward y tg personal polls create; para un reenvío, la lista corresponde al chat de --to. Para repetir una operación con resultado desconocido, pasa el mismo --send-as junto con --operation-id.
Un grupo puede tener un canal guardado como remitente por defecto; Telegram lo hace para el grupo de discusión de tu canal. Allí, un envío, reenvío o encuesta sin --send-as se rechaza (código 2) para evitar publicarlo como el canal: el error indica --send-as <your id> para publicar como tú y --send-as <channel id> para publicar como el canal.
Funciones aún no disponibles
Enviar stickers y ubicaciones sigue en la hoja de ruta. Ya puedes enviar varias fotos o vídeos en un álbum repitiendo --photo o --file.
Guarda una respuesta para revisarla
Un borrador de Telegram te permite revisar el texto en la aplicación y pulsar Enviar personalmente:
tg personal messages send me "Review this text" --draft
tg personal messages send CHAT "A **formatted** reply" --draft --md --reply-to MESSAGE_IDEl comando reemplaza el borrador existente en ese chat o tema del foro y no envía ningún mensaje. Los borradores admiten --topic, --reply-to, --md, --html y --no-preview. El permiso independiente drafts controla el guardado. Se rechazan texto vacío, adjuntos, programación y otras opciones exclusivas del envío; este comando no borra borradores. El recibo devuelve saved: true, en lugar de un mensaje enviado.
Grupos y canales
Todo lo relacionado con un grupo que ejecuta (reglas de moderación, comprobaciones, la lista completa de configuraciones) está en grupos que ejecuta.
tg personal chats inspect https://t.me/+AbCdEf # where an invite or public link leads; does not jointg personal chats members list "Hiking" --all # everyone, with their role and when last seentg personal chats events "Hiking" # who joined, left, was added or removed — 7 daystg personal chats events "Hiking" 'time>="2026-09-01T00:00:00+02:00"'tg personal topics list "Hiking" # a forum group's topics, newest activity firsttg personal search topics "Hiking" "gear"tg personal topics show "Hiking" 12 # one topic: title, closed or pinned, last activitytg personal review 'chat:Hiking' --unanswered # questions nobody answeredTodos estos sólo leen. events lee los mensajes de servicio del chat: quién hizo qué y a quién. Los nombres son join, leave, add, remove, create, title y pin.
Estos cambian algo y las personas en el chat lo ven.
Para un foro, utilice tg personal topics enable <chat> y tg personal topics create <chat> <title>. Un grupo básico requiere --upgrade --yes; mantenga la nueva identificación de chat devuelta por la actualización. Lea topics list después de un resultado de creación desconocido en lugar de repetir la creación. Enviar a su id con tg personal messages send <chat> <text> --topic <id> o tg personal polls create <chat> <question> <answers> --topic <id>. tg personal topics edit <chat> <id> --title <new> cambia el nombre de un tema, --closed on/--closed off lo cierra a nuevos mensajes o lo vuelve a abrir, --pinned on/--pinned off lo fija en la parte superior o lo desancla, y en el tema General (id 1) --hidden on/--hidden off lo oculta de la lista de temas o lo muestra nuevamente. --emoji <emoji> da al tema un icono, en topics edit y en topics create. El emoji debe estar en el conjunto predeterminado de iconos de temas de Telegram, que cualquier cuenta puede usar; tg personal topics icons list lo muestra, y otro emoji se rechaza junto con la lista. topics edit --emoji none quita el icono. tg personal topics order <chat> <id...> coloca los temas fijados en ese orden; no fija ni desancla nada. Repetir cualquiera de estos es seguro. tg personal topics delete <chat> <id> elimina un tema y todos los mensajes que contiene, para todos; no se puede deshacer, por lo que pregunta primero de forma predeterminada; un topics.delete: allow o --allow-dangerous explícito omite la pregunta. El tema general no se puede eliminar.
tg personal chats create "Hiking 2027" @olga 12345 # a supergroup; the people added are toldtg personal chats create "Trail news" --channel # a channel; people join it by its linktg personal chats join https://t.me/+AbCdEf # by an invite link, or a public onetg personal chats leave "Hiking 2027"tg personal chats update "Hiking 2027" --title "Hiking 2028" --description "routes and dates"tg personal chats update "Hiking 2027" --all-can-pin off --only-admins-add ontg personal chats links show "Hiking 2027" # the invite link, if you may see ittg personal chats links reset "Hiking 2027" # a new one; the old one stops workingtg personal chats links create "Hiking 2027" --approval --expire-time 7d # another link; who joins asks firsttg personal chats links create "Hiking 2027" --max-uses 20 # at most 20 people join by ittg personal chats update "Hiking 2027" --join-approval on # everyone asks first, by any linktg personal chats requests list "Hiking 2027" # who asked to join, newest firsttg personal chats requests list "Hiking 2027" 'name:*Ana*' # by name; or link:<link>tg personal chats requests confirm "Hiking 2027" 67890 # let them in; decline turns them awaytg personal chats requests reject "Hiking 2027" --all # every pending request at once; --link narrows ittg personal chats links list "Hiking 2027" # your links, with how many joined and how many waittg personal chats links remove "Hiking 2027" https://t.me/+AbCd # stop one linktg personal chats links update "Hiking 2027" https://t.me/+AbCd --no-approval --max-uses 50 # change only thesetg personal chats members add "Hiking 2027" @kate 67890 # they are toldtg personal chats members remove "Hiking 2027" @kate # their messages staytg personal chats admins add "Hiking 2027" @kate --can pin,deletetg personal chats admins remove "Hiking 2027" @kateUn grupo nuevo es siempre un supergrupo. Alguien cuya configuración de privacidad impide que se agreguen se menciona en la respuesta en provider_metadata.not_added; el grupo está hecho de todos modos. chats join a un grupo cuyos administradores aprueban quién se une, responde requested: true y sale de 0: la solicitud se envía y usted ingresa una vez que un administrador la acepta. Cada uno pasa por la guardia como un cambio chat y cada persona agregada cuenta para el límite por hora.
chats links create crea otro enlace de invitación y no se lo dice a nadie: --approval hace que quien se una pregunte primero, --expire-time lo detiene a la vez (2026-12-01T09:00, o 30m, 2h, 7d a partir de ahora), y --max-uses deja entrar como máximo esa cantidad de personas. chats links update cambia los mismos tres en uno de sus enlaces, el del grupo también (--no-approval desactiva la aprobación, --expire-time never elimina la caducidad); lo que dejas afuera se queda. Un enlace que pregunta primero no tiene límite de uso, por lo que --approval con --max-uses es rechazado. chats update --join-approval on hace que todos pregunten primero, sea cual sea el enlace que utilicen.
En un grupo cuyos administradores aprueban quién se une, chats requests list muestra las solicitudes pendientes, con la nota que envió una persona; sólo los administradores los ven y la lectura no se lo dice a nadie. Una consulta la acota: name: o username: busca personas, link: mantiene a quienes preguntaron a través de un enlace de invitación; Telegram no puede hacer ambas cosas a la vez. confirm y reject responden uno, por el id de la lista. Una solicitud aceptada cuenta para el límite de horas, una rechazada no; la lista de destinatarios comprueba sólo el grupo. Alguien que ya es miembro recibe respuesta con already: true y una solicitud que desaparece termina en la salida 6. --all responde a todas las solicitudes pendientes, o con --link las que llegaron por un enlace; se cuentan primero y una aceptación que supere el límite de horas se rechaza antes de que se permita la entrada a nadie. chats links list muestra sólo sus propios enlaces; Revocar el enlace del propio grupo hace que Telegram emita uno nuevo, como muestra la respuesta.
chats update cambia el título, la descripción y las dos configuraciones que tiene Telegram, de una sola vez; la respuesta es el grupo tal como está y chats show muestra la misma configuración. Las reglas de moderación, chats rules y chats moderate, se encuentran en reglas de moderación.
Salida: tablas, JSON y códigos de salida
En una terminal tg imprime una tabla; en una tubería, o con --json, imprime un valor JSON en la salida estándar y nada más: sin control giratorio, sin tic, sin advertencia. Las notas, advertencias y errores van a stderr en todos los modos. Esto es lo que permite que un script, o su agente, confíen en la respuesta.
tg personal chats list --json | jq -r '.items[].id'tg personal messages list me --jsonl | jq -r 'select(.type == "item") | .data.text' # message text from item records--json: un valor JSON. Cada lista es un objeto, siempre la misma forma:{ "items": [...], "page": { "limit": 20, "has_more": true }, "meta": { ... } }; una lista con más filas indica el paso siguiente enpage.next.--ally--offlineresponden con el mismo objeto. Un solo elemento, no una lista, es{ "item": {...}, "meta": {...} }.- Los mensajes de un chat se paginan con
--cursor, no con un número de página;page.nextlo lleva. --jsonl: los registros de elementos llevan el resultado endata; el registro final indica completitud y paginación. Compruébalo en vez de tratar el flujo como mensajes sin contenedor. Un informe (stats …) es un objeto, por lo que rechaza--jsonl; las listasstats * evidencesiguen emitiéndose como flujo.- Un error usa
{ "error": { "code": "...", "message": "..." } }en stderr. Un rechazo anterior a la salida no escribe resultados y no se confunde con un resultado vacío. Si el flujo ya emitió registros, consérvalos y comprueba su registro final de completitud; si falta el final, el flujo tampoco terminó. - Las lecturas y descargas parciales pueden salir con código
0: compruebacompleteybatchoissue; el JSONL de descarga parcial añadebatch_summary. - Bifurcación en el código de salida, no en el texto. El texto cambia; el código no.
0funcionó,2entrada incorrecta,4no inició sesión,5el perfil puede no hacer esto,6no encontrado,7no está en la lista de destinatarios permitidos,8un límite (el límite por hora o el propio Telegram),9Telegram no respondió a tiempo,14se desconoce si llegó algún mensaje. La tabla completa está en códigos de salida. - Los identificadores son cadenas. Nunca conviertas uno en un número.
--quietdesactiva las notas; todavía se dice un fracaso.-vy-vvagregan detalles a la vista de tabla.--timeout 30sacota todo el comando (500ms,30so2m).tg commands --jsones el árbol de comandos completo, coneffects: { remote, local }en cada comando:remote: "write"cambia algo en Telegram.
if tg personal messages send "Book club" "See you at 7" --json > /dev/null; then
:
else
send_status=$?
case "$send_status" in
14) echo "it may have gone — repeat only with the same --operation-id" ;;
4) echo "run tg personal session start" ;;
esac
fiConecte su agente de IA
Un agente de IA que ejecuta comandos en una terminal (por ejemplo, Claude Code, Codex o Gemini CLI) lee el archivo de skills de tg: las reglas y trampas que --help no puede explicar. tg personal setup lo instala, al igual que tg skill install (--for claude, agents o all, el valor predeterminado). Para instalarlo a mano:
mkdir -p ~/.claude/skills/tg-cli && tg skill show > ~/.claude/skills/tg-cli/SKILL.md # Claude Code
mkdir -p ~/.agents/skills/tg-cli && tg skill show > ~/.agents/skills/tg-cli/SKILL.md # Codex, Gemini CLICursor en local también lee ~/.agents/skills/tg-cli/. Las instrucciones instaladas vienen de la misma versión del paquete que tg. Si el agente no ve la skill, inicia una nueva sesión del agente. Cómo encuentra las skills cada agente: Codex, Gemini CLI, Cursor.
Un agente sin terminal (por ejemplo Claude Desktop o Cursor) se conecta a través de MCP: el servidor MCP.
Cómo se muestra una conversación
tg personal messages list y tg personal search messages imprimen una transcripción en la terminal:
10:05:12 Anna
Shall we call on Thursday?
10:09:03 Boris
↳ Anna: Shall we call on Thursday?
Thursday works.
📎 photo
edited 10:09:30Las horas son locales y una línea marca cada día nuevo. ↳ señala a qué responde el mensaje; ↪, de quién se reenvió; 📎, un adjunto. Los caracteres de control en mensajes y nombres se muestran como texto, sin ejecutarse. Un contacto compartido se imprime como 👤 con su nombre y teléfono; en JSON el adjunto tiene contact con name, first_name, last_name, phone (completo, tal como lo envió Telegram) y user_id, y el almacén lo guarda, así que --offline muestra lo mismo. -v añade identificadores de mensaje, remitente y chat; -vv, todos los datos conocidos del mensaje.
Recibir nuevos mensajes
tg personal watch # new messages, until Ctrl-C or --timeouttg personal watch --jsonl # one {"type":"item","data":message} line per message, then a {"type":"end"} linetg personal watch --jsonl | ./on-message.shtg personal watch --events --jsonl # edits, deletions and reactions tootg personal watch --jsonl --timeout 2m # a timeout ends it normally, with exit code 0Cada línea tiene la forma {"type":"item","data":…}; la última es {"type":"end","complete":true}, o false tras un fallo, que también fija el código de salida. Los campos usan snake_case. Con --events, cada data indica su event: message, edit, delete o reaction. Sin esa opción, data contiene el mensaje sin más. Telegram no indica en qué chat se eliminó un mensaje privado o de un grupo pequeño, por lo que esa línea no incluye chat.
watch comienza a partir de ahora. No se muestra lo que llegó mientras no había nada escuchando. Para mantener actualizado el archivo local, incluido lo que entró mientras esta máquina estaba apagada, use serve, en segundo plano o como servicio del sistema (mantener el archivo local actualizado):
tg personal server start # serve in the background; answers once it is connectedtg personal server statustg personal server install # a systemd user unit or a launchd agent that starts at every login; starts nothing nowQué hizo un comando
tg personal --trace chats list # also show each request on stderrtg personal --no-record chats list # keep nothing of this runtg personal runs list # what was kept, newest firstSiempre se conserva una ejecución fallida. Un registro contiene operaciones, identificadores, recuentos y duraciones; nunca un mensaje, un nombre, un título de chat, un número de teléfono o una clave. Completo: diagnóstico.
Archivo local
Todo lo que lee tg se guarda en este equipo para poder responder sin red:
tg personal chats list --offline # only from the store, never connecttg personal messages sync "Project Alpha" --dry-run # how much a fetch would taketg personal messages sync "Project Alpha" --background # a chat's history, as a jobtg personal store export "Project Alpha" --format markdown --output alpha.mdtg personal store backup ~/tg-store.db # a copy of the store, while it is in useUn comando ordinario todavía consulta Telegram. --offline es para cuando no hay red, o cuando no se desea conectarse; Se rechaza un envío con --offline. Obtención, exportación, búsqueda, copia de seguridad y servicio: el archivo local.
Configuración y permisos del perfil
Los ajustes están en un config.json opcional. El orden de prioridad es: opción → variable de entorno → perfil en el archivo → valores predeterminados del archivo → programa.
tg config show # every setting, and where it came fromtg personal config set limit 50tg work config set permissions.messages readonly # profile "work" changes no messagestg personal config set permissions.messages.send ask # a yes or no before each sendtg personal config set sends_per_hour 10permissions dice lo que puede hacer un perfil, por comando: deny, readonly, ask o allow. Por defecto se permite todo, salvo algunos cambios irreversibles: eliminar mensajes y cerrar sesiones piden confirmación antes de actuar. Un rechazo es el código de salida 5 y el error nombra el comando que lo permite. El archivo no tiene ningún campo para un secreto. Cada configuración y variable: configuración.
Una persona
tg personal contacts show <person> muestra lo que dice Telegram sobre una persona y qué tan activa es en los chats que compartes. tg personal contacts check <person> los califica como posible bot, falso o spammer, con todos los motivos. tg personal contacts context <person> lee lo que el archivo local tiene sobre ellos: sin --chat, en todas las cuentas vinculadas a ellos con contacts link; con --chat, sus mensajes más nuevos en cada chat que nombre. Lo que cada uno pide a Telegram o a una lista pública de spam, y lo que envía a dónde: personas.
Algunos límites que debe conocer: una fecha de registro estimada se adivina a partir de la identificación de la cuenta con una tabla comunitaria, que termina en agosto de 2026; los ID más recientes no reciben estimación. La verificación del bot lee hasta 1000 mensajes almacenados. contacts context devuelve cuerpos de mensajes, por lo que sigue los permisos messages; vincular y desvincular identidades está controlado por contacts y nunca cambia la libreta de direcciones de Telegram.
Siguiente paso
- El archivo local: buscar, recuperar el historial de un chat, exportar, realizar copias de seguridad.
- Configuración: configuración y qué puede hacer un perfil.
- Seguridad: lo que llega al disco, y el control de envío.
- Recetas: trabajo habitual para tu agente de IA.