# Telegram: Cuenta personal (/es/docs/tg/usage)

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.

[Cuenta personal](/llms.mdx/docs/es/tg/usage/content.md) · [Bots](/llms.mdx/docs/es/tg/bot/content.md) · [Administración](/llms.mdx/docs/es/tg/groups/content.md)

## Qué cambió durante mi ausencia

```text prompt
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.

[Buscar y comprobar acuerdos](/llms.mdx/docs/es/search/content.md)

## Reunir materiales para una reunión

```text prompt
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.

[Trabajar con archivos](/llms.mdx/docs/es/prompting/content.md#files-and-voice)

## Entender una conversación larga

```text prompt
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.

[Buscar por tema](/llms.mdx/docs/es/search/content.md)

## Comprobar compromisos antes de responder

```text prompt
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.

[Precisar la petición](/llms.mdx/docs/es/prompting/content.md)

## 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](/llms.mdx/docs/es/tg/commands/content.md); 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](#profiles-the-first-word)).
- **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](/llms.mdx/docs/es/tg/archive/content.md)).
- **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](/llms.mdx/docs/es/tg/security/content.md#the-send-guard)).

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.

```text
tg [profile] [options] <resource> <action> [arguments]
```

## Qué puedes hacer [#qué-puedes-hacer]

| Área | Qué puedes hacer | Empezar con |
|---|---|---|
| Leer | chats, mensajes, un mensaje y sus vecinos, temas del foro | `tg personal chats list`, `tg personal messages list <chat>` |
| Ponerse al día | mensajes no leídos de otras personas; lo que prometiste y lo que está abierto | `tg personal inbox`, `tg personal review` |
| Voz | convierte mensajes de voz en texto, en esta computadora | `tg personal messages transcribe` |
| Archivos | descargar los archivos de un mensaje o de un chat completo | `tg personal messages download` |
| Personas | contactos, el perfil de una persona, un bot check | `tg personal contacts list`, `tg personal contacts show` |
| Buscar | mensajes, archivos, fechas, personas; discusiones por significado | `tg personal search messages`, `tg personal search conversations` |
| Enviar | texto, archivos, voz, respuestas, mensajes programados | `tg personal messages send` |
| Cambiar | editar, reenviar, anclar, eliminar, reaccionar, votar, marcar como leído | `tg personal messages edit`, `tg personal reactions add` |
| Organizar | carpetas | `tg personal chats folders list` |
| Grupos | miembros, enlaces de invitación, solicitudes de participación, temas, administradores | `tg personal chats members list`, `tg personal chats links create` |
| Seguir | nuevos mensajes a medida que llegan; mantener actualizado el archivo local | `tg personal watch`, `tg personal server start` |
| Consultar | lo que hizo un comando; qué puede hacer un perfil | `tg personal runs list`, `tg config show` |

## Lee un chat con tu agente [#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:**

```sh
tg personal messages list "Book club" --limit 5 --json
```

**Ejemplo 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 [#primeros-pasos]

```sh
npm install -g @wirecat/tg-cli
```

```sh
tg skill install --for all  # the agent skill
```

```sh
tg personal setup         # guided app registration, login and agent skill
```

```sh
tg personal chats list --limit 5  # your newest chats
```

```sh
tg personal messages list me  # Saved Messages, the latest 20
```

Espere 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 [#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:

```sh
tg personal session start               # QR code: Settings → Devices → Link Desktop Device
```

```sh
tg personal session start phone         # phone number, the code Telegram sends, your 2FA password
```

```sh
tg personal session start phone --sms   # the same, asking for the code by SMS instead of in the app
```

```sh
tg personal session start qr  # without a terminal (an agent): the QR code as text to paste into the chat
```

El 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](/llms.mdx/docs/es/tg/sessions/content.md).

**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.

```sh
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 number
```

```sh
tg account list                # every profile on this computer and the account each is logged in as
```

```sh
tg personal account sessions list  # every device and app logged in to the account; ends nothing
```

```sh
tg personal session end        # log out on Telegram's side, and delete the session here
```

`session 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 [#perfiles-la-primera-palabra]

Puedes utilizar varias cuentas. El perfil es la primera palabra, no una opción:

```sh
tg personal chats list    # profile "personal"
```

```sh
tg work chats list        # profile "work"
export TG_PROFILE=work    # or for a whole shell session
```

**La 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](/llms.mdx/docs/es/tg/profiles/content.md)).

## Cómo indicar un chat [#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`.
- `me` para 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]

**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](#marking-a-chat-read)).

### Chats [#chats]

```sh
tg personal chats list                     # newest first, archived chats included
```

```sh
tg personal chats list 'unread_count>0 kind:group' --offline  # only groups with unread messages
```

```sh
tg personal chats list 'title:*book*' --offline  # titles containing "book"; at least 3 characters
```

```sh
tg personal chats show "Book club"         # kind, unread count, last message, who is in it
```

Una 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](#groups-and-channels).

### Mensajes [#mensajes]

```sh
tg personal messages list "Book club"           # the latest 20, oldest first
```

```sh
tg personal messages list "Book club" --limit 50
```

```sh
tg personal messages list "Hiking" topic:12   # one forum topic; topics list shows the ids
```

```sh
tg personal messages show "Book club" 4242      # one message
```

```sh
tg personal messages context "Book club" 4242   # it, and 5 messages either side
```

```sh
tg personal messages context "Book club" 4242 --before-n 2 --after-n 10
```

En `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 [#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](/llms.mdx/docs/es/tg/topic-search/content.md)).

### Qué necesita respuesta [#qué-necesita-respuesta]

```sh
tg personal inbox            # other people's unread messages, in every chat
```

```sh
tg personal inbox 'date>2h'  # everything that came in during the last two hours
```

```sh
tg personal inbox --new      # what arrived since the last --new — for scheduled runs
```

```sh
tg personal inbox --new --jsonl  # the same for a script: one message per line
```

`inbox` 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` [#compromisos-pendientes-review]

```sh
tg personal review                         # the last 3 days
```

```sh
tg personal review 'date>"2026-09-23T09:00:00+02:00"'  # from where the last review ended
```

```sh
tg personal review 'chat:"Book club"' --json
```

Muestra 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 [#preguntas-sin-respuesta]

```sh
tg personal review --unanswered            # questions nobody answered in 24 hours
```

```sh
tg 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 [#mensajes-de-voz]

```sh
tg personal messages transcribe "Book club" 4242  # by Telegram where it can, else a model here
```

```sh
tg personal messages transcribe "Book club" 4242 --local  # only the model on this machine
```

```sh
tg personal messages list "Book club" --transcribe  # every voice message shown that has no text yet
```

```sh
tg personal inbox --transcribe
```

```sh
tg personal review --transcribe
```

```sh
tg personal messages list "Book club" --transcribe --model gigaam-v3
```

La 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:

```sh
tg personal models list kind:audio          # the models, which is downloaded, which is the default
```

```sh
tg 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](/llms.mdx/docs/es/tg/configuration/content.md)). 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 [#archivos]

```sh
tg personal messages download "Book club" 4242 --output-dir ~/Downloads  # one message's files
```

```sh
tg personal messages download "Book club" --all --output-dir ~/tg-files  # every file of the chat, newest first
```

Se 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](/llms.mdx/docs/es/tg/attachments/content.md).

### Personas [#personas]

```sh
tg personal contacts list              # people you have a one-to-one chat with, newest first
```

```sh
tg personal contacts list 'name:*ann*' --order name
```

```sh
tg personal contacts show @example_user  # their bio and the chats you share
```

```sh
tg personal contacts lookup            # who has a phone number — asks for it, or reads it from stdin
```

```sh
tg personal contacts sync              # your whole Telegram contact list into the local store
```

```sh
tg personal contacts show @example_user  # flags, last seen, registered, messages per shared chat
```

```sh
tg personal contacts context @example_user --chat "Book club"  # their latest messages there
```

```sh
tg personal contacts check @example_user  # does the account look like a bot or a spammer
```

`contacts 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](/llms.mdx/docs/es/tg/people/content.md).

Para cambiar contactos y tu perfil:

```sh
tg personal contacts add @example_user  # under the name they show
```

```sh
tg personal contacts rename @example_user Ann "from work"  # a name only you see
```

```sh
tg personal contacts remove @example_user  # the chat stays
```

```sh
tg personal contacts block @example_user  # they need not be a contact
```

```sh
tg personal contacts unblock @example_user
```

```sh
tg personal contacts import people.txt  # one "number, name" per line; never numbers as arguments
```

```sh
tg personal account update --first-name Ann --description "about me" --photo me.jpg
```

```sh
tg personal account sessions end --others  # logs out every other device, your phone too; asks first
```

`contacts 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 [#páginas]

Las listas muestran `limit` filas (20 por defecto). `chats list`, `contacts list`, `chats members list` y `topics` aceptan `--page` y `--all`:

```sh
tg personal contacts list --limit 5    # five a page
```

```sh
tg personal contacts list --limit 5 --page 2  # the sixth to the tenth
```

```sh
tg 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:

```sh
tg personal messages list "Book club" "id<4242"  # older than message 4242
```

```sh
tg personal messages list "Book club" "id>4242"  # newer than 4242, oldest first
```

```sh
tg personal messages list "Book club" "date>2h"  # what came in during the last two hours
```

```sh
tg personal messages list "Book club" 'date>"2026-09-20T09:00:00+02:00"'
```

```sh
tg personal messages list "Book club" "date<1d"  # what came before this time yesterday
```

En 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 [#encontrar-un-chat-antes-de-escribir]

```sh
tg personal chats list 'title:*book* kind:group' --offline  # groups with "book" in the title
```

```sh
tg personal contacts list 'name:*ann*'  # people by name or @username
```

```sh
tg personal search all "contract"            # messages and notes kept here, and Telegram's own search
```

```sh
tg personal search all "contract" --offline  # only this computer; the query never leaves it
```

```sh
tg personal search messages "contract"       # the text of every message this machine has kept
```

```sh
tg personal search messages 'contract chat:"Book club"'
```

```sh
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](/llms.mdx/docs/es/tg/query-language/content.md): `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](/llms.mdx/docs/es/tg/search/content.md). Una vez que tengas el chat, usa su id.

## Enviar [#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](/llms.mdx/docs/es/tg/security/content.md#the-send-guard)). Se registra cada intento, nunca su texto: `tg personal sends list`.

```sh
tg personal messages send me "a note to myself"
```

```sh
tg personal messages send "Book club" "See you at 7" --silent  # no notification
```

```sh
tg personal messages send "Book club" "a link, no card" --no-preview
```

```sh
tg personal messages send "Book club" "**Bold** and _italic_" --md  # Telegram Markdown
```

```sh
tg 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 [#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:

```sh
printf 'first line\n\nthird line' | tg personal messages send me
tg personal messages send "Book club" < note.txt
```

### Programar un envío [#programar-un-envío]

```sh
tg personal messages send "Book club" "Tomorrow" --at-time 2026-10-01T09:00  # local time
```

```sh
tg personal messages send "Book club" "In two hours" --at-time 2h  # or 30m, 1d from now
```

```sh
tg 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 [#archivos-fotos-y-voz]

```sh
tg personal messages send "Book club" "The agenda" --file agenda.pdf  # byte for byte; the text is the caption
```

```sh
tg personal messages send "Book club" --photo picture.jpg     # recompressed by Telegram
```

```sh
tg personal messages send "Book club" --file trip.mp4         # a video plays in the chat
```

```sh
tg personal messages send "Book club" --file trip.mp4 --as-file  # the same video as a file to download
```

```sh
tg personal messages send "Book club" --voice note.ogg        # a voice message, alone, with no text
```

```sh
tg personal messages send "Book club" --file 3f9a.pdf --filename "Report Q3.pdf"  # the name others see
```

Repite `--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`.

```sh
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](/llms.mdx/docs/es/tg/attachments/content.md).

### Responder a un mensaje [#responder-a-un-mensaje]

```sh
tg personal messages send "Book club" "Agreed" --reply-to 4242
```

Una respuesta es un envío: admite todas sus opciones.

### Reacciones y encuestas [#reacciones-y-encuestas]

```sh
tg personal reactions add "Book club" 4242 👍  # replaces the reaction you had
```

```sh
tg personal reactions remove "Book club" 4242
```

```sh
tg personal reactions list "Book club" 4242 reaction:🔥 --limit 20  # who reacted, newest first; --cursor goes on
```

```sh
tg personal polls show "Book club" 4250    # the poll and its answer ids
```

```sh
tg personal polls voters "Book club" 4250 'answers:<answer id>'  # who chose it; not in an anonymous poll
```

```sh
tg personal polls vote "Book club" 4250 <answer id>
```

```sh
tg personal polls vote "Book club" 4250 --retract
```

```sh
tg personal polls create "Book club" "Which day?" Monday Tuesday --anonymous
```

```sh
tg personal polls create "Book club" "Pizza now?" yes no --close-time 5m  # closes by itself; 5s to 10m
```

```sh
tg personal polls close "Book club" 4250   # your own poll; it cannot be reopened
```

```sh
tg personal polls create "Book club" "2+2?" 3 4 5 --quiz --correct 2 --solution "Four."  # a quiz; a vote is final
```

Al 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 [#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.

```sh
tg personal messages show "Shop bot" 4300   # the buttons are numbered under the message
```

```sh
tg 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 text
```

```sh
tg 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 you
```

El 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 [#editar-reenviar-fijar-y-eliminar]

```sh
tg personal messages edit "Book club" 4242 "the corrected text"  # your own message; --md or --html as in a send
```

```sh
tg personal messages forward "Book club" 4242 --to me       # checked against the chat it goes to
```

```sh
tg personal messages forward "Book club" 4242 --to "Hiking" --topic 12  # into one topic of a forum
```

```sh
tg personal messages pin "Book club" 4242                   # quiet unless --notify
```

```sh
tg personal messages unpin "Book club" 4242
```

```sh
tg personal messages delete me 4242 4243 --allow-dangerous  # at most 10, for you only
```

```sh
tg personal messages delete me 4242 --allow-dangerous --for-everyone
```

Una 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 [#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:

```sh
tg personal messages send "Book club" "See you at 7" --operation-id <id from the error>
```

```sh
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 [#tu-lista-de-chats-archivar-fijar-marcar-como-no-leído-silenciar]

```sh
tg personal chats archive "Book club"        # into the archive; `unarchive` brings it back
```

```sh
tg personal chats pin "Book club"            # to the top of your list; `unpin` lets it move down
```

```sh
tg personal chats mark-unread "Book club"    # the dot on your own devices; nobody sees it
```

```sh
tg personal chats mute "Book club" --until 2h  # without --until, for good; `unmute` hears it again
```

Esto 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 [#marcar-un-chat-como-leído]

```sh
tg personal chats mark-read "Book club"      # up to the newest message
```

```sh
tg personal chats mark-read "Book club" --until-id 4242  # only up to this one
```

```sh
tg personal chats mark-read "Hiking" --topic 12  # only this forum topic
```

```sh
tg personal messages list "Book club"  # read without sending a receipt
```

La otra persona lo ve. Pasa por los controles como acción `read` y no cuenta para el límite por hora.

### Carpetas [#carpetas]

```sh
tg personal chats folders list                     # your folders, in the order the app shows them
```

```sh
tg personal chats folders show "Trips"             # one folder, with the names of its chats
```

```sh
tg personal chats folders create "Trips" --chat "Hiking" --chat @kate
```

```sh
tg personal chats folders update "Trips" --title "Travel" --add "Climbing" --remove @kate
```

```sh
tg personal chats folders delete "Travel"          # the chats stay
```

```sh
tg personal chats folders order "Travel" "Work"    # these first; the rest keep their order after them
```

```sh
tg personal chats folders join https://t.me/addlist/AbCdEf  # a folder someone shared: joins every chat in it
```

```sh
tg personal chats folders create "Inbox" --include contacts,groups --skip muted,archived --emoji 📥
```

```sh
tg personal chats folders update "Inbox" --exclude-chat "Noisy group" --pin @kate
```

```sh
tg personal chats folders update "Inbox" --include none  # no kinds any more; only the chats named in it
```

Una 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 [#comentarios-de-un-canal]

```sh
tg personal messages comments "Rozetked" 27644     # the comments under post 27644, oldest first
```

```sh
tg personal messages comments "Rozetked" 27644 "id<3732413"
```

```sh
tg personal messages send "My channel" "Thanks!" --comment-to 120
```

Los 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 [#publicar-como-un-canal]

En un grupo donde puedas publicar como uno de tus canales, consulta primero los remitentes disponibles y elige uno:

```sh
tg personal chats send-as "Book club"
```

```sh
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 [#funciones-aún-no-disponibles]

Enviar stickers y ubicaciones sigue en la [hoja de ruta](/llms.mdx/docs/es/tg/roadmap/content.md). Ya puedes enviar varias fotos o vídeos en un álbum repitiendo `--photo` o `--file`.

### Guarda una respuesta para revisarla [#guarda-una-respuesta-para-revisarla]

Un borrador de Telegram te permite revisar el texto en la aplicación y pulsar Enviar personalmente:

```sh
tg personal messages send me "Review this text" --draft
tg personal messages send CHAT "A **formatted** reply" --draft --md --reply-to MESSAGE_ID
```

El 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 [#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](/llms.mdx/docs/es/tg/groups/content.md).

```sh
tg personal chats inspect https://t.me/+AbCdEf     # where an invite or public link leads; does not join
```

```sh
tg personal chats members list "Hiking" --all      # everyone, with their role and when last seen
```

```sh
tg personal chats events "Hiking"                  # who joined, left, was added or removed — 7 days
```

```sh
tg personal chats events "Hiking" 'time>="2026-09-01T00:00:00+02:00"'
```

```sh
tg personal topics list "Hiking"                   # a forum group's topics, newest activity first
```

```sh
tg personal search topics "Hiking" "gear"
```

```sh
tg personal topics show "Hiking" 12                # one topic: title, closed or pinned, last activity
```

```sh
tg personal review 'chat:Hiking' --unanswered    # questions nobody answered
```

Todos 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.

```sh
tg personal chats create "Hiking 2027" @olga 12345  # a supergroup; the people added are told
```

```sh
tg personal chats create "Trail news" --channel    # a channel; people join it by its link
```

```sh
tg personal chats join https://t.me/+AbCdEf        # by an invite link, or a public one
```

```sh
tg personal chats leave "Hiking 2027"
```

```sh
tg personal chats update "Hiking 2027" --title "Hiking 2028" --description "routes and dates"
```

```sh
tg personal chats update "Hiking 2027" --all-can-pin off --only-admins-add on
```

```sh
tg personal chats links show "Hiking 2027"          # the invite link, if you may see it
```

```sh
tg personal chats links reset "Hiking 2027"         # a new one; the old one stops working
```

```sh
tg personal chats links create "Hiking 2027" --approval --expire-time 7d  # another link; who joins asks first
```

```sh
tg personal chats links create "Hiking 2027" --max-uses 20  # at most 20 people join by it
```

```sh
tg personal chats update "Hiking 2027" --join-approval on  # everyone asks first, by any link
```

```sh
tg personal chats requests list "Hiking 2027"      # who asked to join, newest first
```

```sh
tg personal chats requests list "Hiking 2027" 'name:*Ana*'  # by name; or link:<link>
```

```sh
tg personal chats requests confirm "Hiking 2027" 67890  # let them in; decline turns them away
```

```sh
tg personal chats requests reject "Hiking 2027" --all  # every pending request at once; --link narrows it
```

```sh
tg personal chats links list "Hiking 2027"          # your links, with how many joined and how many wait
```

```sh
tg personal chats links remove "Hiking 2027" https://t.me/+AbCd  # stop one link
```

```sh
tg personal chats links update "Hiking 2027" https://t.me/+AbCd --no-approval --max-uses 50  # change only these
```

```sh
tg personal chats members add "Hiking 2027" @kate 67890  # they are told
```

```sh
tg personal chats members remove "Hiking 2027" @kate  # their messages stay
```

```sh
tg personal chats admins add "Hiking 2027" @kate --can pin,delete
```

```sh
tg personal chats admins remove "Hiking 2027" @kate
```

Un 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](/llms.mdx/docs/es/tg/groups/content.md#rules).

## Salida: tablas, JSON y códigos de salida [#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.

```sh
tg personal chats list --json | jq -r '.items[].id'
```

```sh
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 en `page.next`. `--all` y `--offline` responden 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.next` lo lleva.
- `--jsonl`: los registros de elementos llevan el resultado en `data`; 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 listas `stats * evidence` siguen 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`: comprueba `complete` y `batch` o `issue`; el JSONL de descarga parcial añade `batch_summary`.
- **Bifurcación en el código de salida, no en el texto.** El texto cambia; el código no. `0` funcionó, `2` entrada incorrecta, `4` no inició sesión, `5` el perfil puede no hacer esto, `6` no encontrado, `7` no está en la lista de destinatarios permitidos, `8` un límite (el límite por hora o el propio Telegram), `9` Telegram no respondió a tiempo, `14` se desconoce si llegó algún mensaje. La tabla completa está en [códigos de salida](/llms.mdx/docs/es/tg/commands/content.md#exit-codes).
- **Los identificadores son cadenas.** Nunca conviertas uno en un número.
- `--quiet` desactiva las notas; todavía se dice un fracaso. `-v` y `-vv` agregan detalles a la vista de tabla.
- `--timeout 30s` acota todo el comando (`500ms`, `30s` o `2m`).
- `tg commands --json` es el árbol de comandos completo, con `effects: { remote, local }` en cada comando: `remote: "write"` cambia algo en Telegram.

```sh
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
fi
```

## Conecte su agente de IA [#conecte-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:

```sh
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 CLI
```

Cursor 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](https://learn.chatgpt.com/docs/build-skills), [Gemini CLI](https://geminicli.com/docs/cli/skills/), [Cursor](https://cursor.com/docs/skills).

Un agente sin terminal (por ejemplo Claude Desktop o Cursor) se conecta a través de MCP: [el servidor MCP](/llms.mdx/docs/es/tg/mcp/content.md).

## Cómo se muestra una conversación [#cómo-se-muestra-una-conversación]

`tg personal messages list` y `tg personal search messages` imprimen una transcripción en la terminal:

```text
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:30
```

Las 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 [#recibir-nuevos-mensajes]

```sh
tg personal watch                  # new messages, until Ctrl-C or --timeout
```

```sh
tg personal watch --jsonl          # one {"type":"item","data":message} line per message, then a {"type":"end"} line
```

```sh
tg personal watch --jsonl | ./on-message.sh
```

```sh
tg personal watch --events --jsonl  # edits, deletions and reactions too
```

```sh
tg personal watch --jsonl --timeout 2m  # a timeout ends it normally, with exit code 0
```

Cada 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](/llms.mdx/docs/es/tg/archive/content.md#keeping-it-current-serve)):

```sh
tg personal server start  # serve in the background; answers once it is connected
```

```sh
tg personal server status
```

```sh
tg personal server install  # a systemd user unit or a launchd agent that starts at every login; starts nothing now
```

## Qué hizo un comando [#qué-hizo-un-comando]

```sh
tg personal --trace chats list          # also show each request on stderr
```

```sh
tg personal --no-record chats list      # keep nothing of this run
```

```sh
tg personal runs list          # what was kept, newest first
```

Siempre 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](/llms.mdx/docs/es/tg/diagnostics/content.md).

## Archivo local [#archivo-local]

Todo lo que lee `tg` se guarda en este equipo para poder responder sin red:

```sh
tg personal chats list --offline                  # only from the store, never connect
```

```sh
tg personal messages sync "Project Alpha" --dry-run  # how much a fetch would take
```

```sh
tg personal messages sync "Project Alpha" --background  # a chat's history, as a job
```

```sh
tg personal store export "Project Alpha" --format markdown --output alpha.md
```

```sh
tg personal store backup ~/tg-store.db            # a copy of the store, while it is in use
```

Un 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](/llms.mdx/docs/es/tg/archive/content.md).

## Configuración y permisos del perfil [#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**.

```sh
tg config show                                 # every setting, and where it came from
```

```sh
tg personal config set limit 50
```

```sh
tg work config set permissions.messages readonly   # profile "work" changes no messages
```

```sh
tg personal config set permissions.messages.send ask  # a yes or no before each send
```

```sh
tg personal config set sends_per_hour 10
```

`permissions` 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](/llms.mdx/docs/es/tg/configuration/content.md).

## Una persona [#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](/llms.mdx/docs/es/tg/people/content.md).

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 [#siguiente-paso]

- [El archivo local](/llms.mdx/docs/es/tg/archive/content.md): buscar, recuperar el historial de un chat, exportar, realizar copias de seguridad.
- [Configuración](/llms.mdx/docs/es/tg/configuration/content.md): configuración y qué puede hacer un perfil.
- [Seguridad](/llms.mdx/docs/es/tg/security/content.md): lo que llega al disco, y el control de envío.
- [Recetas](/llms.mdx/docs/es/tg/recipes/content.md): trabajo habitual para tu agente de IA.
