# API: scripts, pasos y carpetas

_API · 5 min de lectura · Actualizado 2026-10-22 · https://lanachat.ai/guides/es/api-scripts/_

Un **script** es una secuencia fija de pasos para una creadora: cada paso es un texto, medios opcionales del Vault, un precio en Stars y una espera antes del siguiente. Los scripts están en carpetas. Se puede marcar un script por creadora como **first**: se ejecuta en conversaciones nuevas.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/scripts` | Listar scripts (`creator_id=` requerido, `folder_id=`, `active=true`) | `can_setup` | Planned |
| POST | `/scripts` | Crear un script con sus pasos | `can_setup` | Planned |
| GET | `/scripts/{id}` | Un script y sus pasos | `can_setup` | Planned |
| PUT | `/scripts/{id}` | Reemplazar un script (nombre, pasos, carpeta, cuentas) | `can_setup` | Planned |
| PATCH | `/scripts/{id}` | Activar o desactivar, marcar como first, mover a carpeta | `can_setup` | Planned |
| POST | `/scripts/{id}/duplicate` | Copiar un script (la copia nunca es first) | `can_setup` | Planned |
| DELETE | `/scripts/{id}` | Eliminar un script | `can_setup` | Planned |
| GET | `/scripts/folders` | Carpetas de una creadora (`creator_id=`) | `can_setup` | Planned |
| POST | `/scripts/folders` | Crear una carpeta | `can_setup` | Planned |
| PATCH | `/scripts/folders/{id}` | Renombrar una carpeta | `can_setup` | Planned |
| DELETE | `/scripts/folders/{id}` | Eliminar una carpeta; sus scripts se mueven a "No folder" | `can_setup` | Planned |
| POST | `/conversations/{id}/script` | Ejecutar un script en una conversación (ver [Conversations](https://lanachat.ai/guides/es/api-conversations/)) | `can_chat` | Planned |

## The script object

```json
{
  "id": "scr_204",
  "creator_id": "cr_lea",
  "name": "Welcome message",
  "goal": "First sale within the first day",
  "folder_id": "fld_12",
  "active": true,
  "first": true,
  "account_ids": null,
  "steps": [
    { "id": "st_1", "name": "Hello", "text": "Hey you 😊 glad you found me here", "media": [], "wait_minutes": 0, "pricing": { "mode": "free" } },
    { "id": "st_2", "name": "First set", "text": "Made this one this morning…", "media": ["med_5521", "med_5522"], "wait_minutes": 20, "pricing": { "mode": "paid", "stars": 250, "discount_stars": 200 } }
  ],
  "created_at": "2026-09-30T10:00:00Z",
  "updated_at": "2026-10-05T16:22:00Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Comienza con `scr_` |
| `creator_id` | string | La creadora cuyos fans lo reciben |
| `name` | string | Su nombre en la Console |
| `goal` | string or null | Para qué es el script, en tus palabras |
| `folder_id` | string or null | Su carpeta; `null` es "No folder" |
| `active` | boolean | `false` significa que nunca se ejecuta |
| `first` | boolean | `true` significa que se ejecuta en conversaciones nuevas |
| `account_ids` | array or null | `null` significa todas las cuentas Telegram de la creadora; un array significa solo esas (al menos una) |
| `steps` | array | Los pasos, en orden (ver abajo) |
| `created_at`, `updated_at` | string | ISO 8601, UTC |

Cada paso tiene:

| Field | Type | Description |
|---|---|---|
| `id` | string | Comienza con `st_` |
| `name` | string | Su nombre en el editor |
| `text` | string | El mensaje que recibe el fan |
| `media` | array of strings | IDs de medios del [Vault](https://lanachat.ai/guides/es/api-vault/) de la creadora |
| `wait_minutes` | number | Espera antes de enviar este paso |
| `pricing.mode` | string | `free`, `vault` (cada medio a su precio en Vault) o `paid` (un precio para todo el paso) |
| `pricing.stars` | number | Precio en Stars, cuando `mode` es `paid` |
| `pricing.discount_stars` | number | Precio menor opcional en Stars |

Poner `first: true` en un script lo quita de los otros scripts de la creadora.

## Scripts

### Listar scripts

`GET /scripts` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sí | La creadora |
| `folder_id` | string | No | Solo los scripts de esta carpeta |
| `active` | boolean | No | `true` lista solo los scripts activos |
| `limit`, `cursor` | number, string | No | [Paginación](https://lanachat.ai/guides/es/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/scripts?creator_id=cr_lea&active=true" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La respuesta es una página de objetos script en `data`, con `next_cursor`. Sin `creator_id` la API responde `400`.

### Crear un script

`POST /scripts` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sí | La creadora |
| `name` | string | Sí | Su nombre |
| `steps` | array | Sí | Los pasos, como en el objeto arriba (sin `id`) |
| `goal` | string | No | Para qué sirve |
| `folder_id` | string | No | Carpeta de la misma creadora |
| `account_ids` | array of strings | No | Solo estas cuentas; omitir para todas |

```bash
curl -X POST https://api.lanachat.ai/v1/scripts \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"creator_id": "cr_lea", "name": "Win back", "steps": [{"name": "Miss you", "text": "Hey stranger, where did you go?", "wait_minutes": 0, "pricing": {"mode": "free"}}]}'
```

```json
{
  "id": "scr_231",
  "creator_id": "cr_lea",
  "name": "Win back",
  "goal": null,
  "folder_id": null,
  "active": true,
  "first": false,
  "account_ids": null,
  "steps": [ { "id": "st_1", "name": "Miss you", "text": "Hey stranger, where did you go?", "media": [], "wait_minutes": 0, "pricing": { "mode": "free" } } ],
  "created_at": "2026-10-06T14:30:00Z",
  "updated_at": "2026-10-06T14:30:00Z"
}
```

La respuesta es el script nuevo (`201`), activo, no first, sin carpeta. Un ID de medio de otro Vault es rechazado (`400`).

### Obtener un script

`GET /scripts/{id}` · `can_setup`

```bash
curl https://api.lanachat.ai/v1/scripts/scr_204 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La respuesta es el objeto script con todos sus pasos.

### Reemplazar un script

`PUT /scripts/{id}` · `can_setup`

Envía el script completo: `name`, `steps`, `folder_id` y `account_ids`, como en Crear un script. Los pasos que omitas se eliminan.

```bash
curl -X PUT https://api.lanachat.ai/v1/scripts/scr_231 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Win back", "folder_id": "fld_12", "account_ids": null, "steps": [{"name": "Miss you", "text": "Hey stranger, where did you go?", "wait_minutes": 0, "pricing": {"mode": "free"}}, {"name": "Gift", "text": "Kept this one for you", "media": ["med_5522"], "wait_minutes": 30, "pricing": {"mode": "paid", "stars": 200}}]}'
```

La respuesta es el script actualizado. Un array vacío en `account_ids` responde `400`: usa `null` para todas las cuentas.

### Activar, marcar first, mover

`PATCH /scripts/{id}` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `active` | boolean | No | Activar o desactivar |
| `first` | boolean | No | `true` lo hace el script de conversaciones nuevas |
| `folder_id` | string or null | No | Moverlo; `null` es "No folder" |

```bash
curl -X PATCH https://api.lanachat.ai/v1/scripts/scr_231 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first": true}'
```

La respuesta es el script actualizado. El script first anterior de la creadora pierde `first`.

### Duplicar un script

`POST /scripts/{id}/duplicate` · `can_setup`

```bash
curl -X POST https://api.lanachat.ai/v1/scripts/scr_204/duplicate \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

La respuesta es la copia (`201`). La copia nunca es first.

### Eliminar un script

`DELETE /scripts/{id}` · `can_setup`

```bash
curl -X DELETE https://api.lanachat.ai/v1/scripts/scr_231 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

## Carpetas

### Listar carpetas

`GET /scripts/folders` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sí | La creadora |

```bash
curl "https://api.lanachat.ai/v1/scripts/folders?creator_id=cr_lea" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

### Crear una carpeta

`POST /scripts/folders` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sí | La creadora |
| `name` | string | Sí | Nombre de la carpeta |

```bash
curl -X POST https://api.lanachat.ai/v1/scripts/folders \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"creator_id": "cr_lea", "name": "Win back"}'
```

### Renombrar una carpeta

`PATCH /scripts/folders/{id}` · `can_setup`

```bash
curl -X PATCH https://api.lanachat.ai/v1/scripts/folders/fld_12 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome"}'
```

### Eliminar una carpeta

`DELETE /scripts/folders/{id}` · `can_setup`

```bash
curl -X DELETE https://api.lanachat.ai/v1/scripts/folders/fld_12 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Sus scripts se conservan y se mueven a "No folder".

## Ejecutar un script en una conversación

`POST /conversations/{id}/script` · `can_chat`

Inicia un script en la conversación de un fan: `state` pasa a ser `script` hasta que termina. El cuerpo, ejemplo y reglas están en [Conversations](https://lanachat.ai/guides/es/api-conversations/).

## Artículos relacionados

- [API de LanaChat: inicio rápido, autenticación y errores](https://lanachat.ai/guides/es/api-overview/)
- [Scripts: escribir, organizar y usarlos](https://lanachat.ai/guides/es/scripts/)
- [Scripts vs. IA: cuándo el bot sigue un guion](https://lanachat.ai/guides/es/scripts-vs-ai/)