# API: script, passaggi e cartelle

_API · 5 min di lettura · Aggiornato 2026-10-22 · https://lanachat.ai/guides/it/api-scripts/_

Un **script** è una sequenza fissa di passaggi per una creator: ogni passaggio è un testo, media opzionali dal Vault, un prezzo in Stars e un'attesa prima del successivo. Gli script sono organizzati in cartelle. Uno script per creator può essere contrassegnato come **first**: viene eseguito nelle nuove conversazioni.

## Endpoint

| Metodo | Percorso | Descrizione | Permesso | Stato |
|---|---|---|---|---|
| GET | `/scripts` | Elenca gli script (`creator_id=` obbligatorio, `folder_id=`, `active=true`) | `can_setup` | Planned |
| POST | `/scripts` | Crea uno script con i suoi passaggi | `can_setup` | Planned |
| GET | `/scripts/{id}` | Uno script e i suoi passaggi | `can_setup` | Planned |
| PUT | `/scripts/{id}` | Sostituisce uno script (nome, passaggi, cartella, account) | `can_setup` | Planned |
| PATCH | `/scripts/{id}` | Attiva/disattiva, contrassegna come first, sposta in una cartella | `can_setup` | Planned |
| POST | `/scripts/{id}/duplicate` | Duplica uno script (la copia non è mai first) | `can_setup` | Planned |
| DELETE | `/scripts/{id}` | Elimina uno script | `can_setup` | Planned |
| GET | `/scripts/folders` | Cartelle di una creator (`creator_id=`) | `can_setup` | Planned |
| POST | `/scripts/folders` | Crea una cartella | `can_setup` | Planned |
| PATCH | `/scripts/folders/{id}` | Rinomina una cartella | `can_setup` | Planned |
| DELETE | `/scripts/folders/{id}` | Elimina una cartella; gli script si spostano in "No folder" | `can_setup` | Planned |
| POST | `/conversations/{id}/script` | Esegue uno script su una conversazione (vedi [Conversations](https://lanachat.ai/guides/it/api-conversations/)) | `can_chat` | Planned |

## L'oggetto script

```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"
}
```

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | stringa | Inizia con `scr_` |
| `creator_id` | stringa | La creator i cui fans lo ricevono |
| `name` | stringa | Il nome nella Console |
| `goal` | stringa o null | A cosa serve lo script, a parole tue |
| `folder_id` | stringa o null | La cartella; `null` è "No folder" |
| `active` | booleano | `false` significa che non viene mai eseguito |
| `first` | booleano | `true` significa che si esegue nelle nuove conversazioni |
| `account_ids` | array o null | `null` significa tutti gli account Telegram della creator; un array significa solo quelli (almeno uno) |
| `steps` | array | I passaggi, in ordine (vedi sotto) |
| `created_at`, `updated_at` | stringa | ISO 8601, UTC |

Ogni passaggio ha:

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | stringa | Inizia con `st_` |
| `name` | stringa | Il nome nell'editor |
| `text` | stringa | Il messaggio che riceve il fan |
| `media` | array di stringhe | Id dei media dal [Vault](https://lanachat.ai/guides/it/api-vault/) della creator |
| `wait_minutes` | numero | Attesa prima dell'invio del passaggio |
| `pricing.mode` | stringa | `free`, `vault` (ogni media al suo prezzo Vault) o `paid` (un prezzo per tutto il passaggio) |
| `pricing.stars` | numero | Prezzo in Stars, se `mode` è `paid` |
| `pricing.discount_stars` | numero | Prezzo inferiore opzionale in Stars |

Impostare `first: true` su uno script lo rimuove dagli altri script della creator.

## Script

### Elenca gli script

`GET /scripts` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | stringa | Sì | La creator |
| `folder_id` | stringa | No | Solo gli script di questa cartella |
| `active` | booleano | No | `true` elenca solo gli script attivi |
| `limit`, `cursor` | numero, stringa | No | [Paginazione](https://lanachat.ai/guides/it/api-overview/) |

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

La risposta è una pagina di oggetti script in `data`, con `next_cursor`. Senza `creator_id` l'API risponde `400`.

### Crea uno script

`POST /scripts` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | stringa | Sì | La creator |
| `name` | stringa | Sì | Il nome |
| `steps` | array | Sì | I passaggi, come nell'oggetto sopra (senza `id`) |
| `goal` | stringa | No | A cosa serve |
| `folder_id` | stringa | No | Una cartella della stessa creator |
| `account_ids` | array di stringhe | No | Solo questi account; omettilo per tutti |

```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 risposta è il nuovo script (`201`), attivo, non first, senza cartella. Un id media da Vault di un'altra creator è rifiutato (`400`).

### Ottieni uno script

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

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

La risposta è l'oggetto script con tutti i suoi passaggi.

### Sostituisci uno script

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

Invia lo script completo: `name`, `steps`, `folder_id` e `account_ids`, come in Crea uno script. I passaggi omessi vengono rimossi.

```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 risposta è lo script aggiornato. Un array `account_ids` vuoto risponde `400`: usa `null` per tutti gli account.

### Attiva, contrassegna first, sposta

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `active` | booleano | No | Attiva o disattiva |
| `first` | booleano | No | `true` lo rende lo script delle nuove conversazioni |
| `folder_id` | stringa o null | No | Spostalo; `null` è "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 risposta è lo script aggiornato. Il precedente script first della creator perde il flag `first`.

### Duplica uno 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 risposta è la copia (`201`). La copia non è mai first.

### Elimina uno script

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

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

## Cartelle

### Elenca le cartelle

`GET /scripts/folders` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | stringa | Sì | La creator |

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

### Crea una cartella

`POST /scripts/folders` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | stringa | Sì | La creator |
| `name` | stringa | Sì | Nome della cartella |

```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"}'
```

### Rinomina una cartella

`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"}'
```

### Elimina una cartella

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

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

Gli script della cartella vengono mantenuti e spostati in "No folder".

## Esegui uno script su una conversazione

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

Avvia uno script su una conversazione con un fan: lo `state` diventa `script` finché non termina. Corpo, esempio e regole sono in [Conversations](https://lanachat.ai/guides/it/api-conversations/).

## Articoli correlati

- [API LanaChat: avvio rapido, autenticazione ed errori](https://lanachat.ai/guides/it/api-overview/)
- [Script: scrivili, organizzali e usali](https://lanachat.ai/guides/it/scripts/)
- [Script vs. AI: quando il bot segue uno script](https://lanachat.ai/guides/it/scripts-vs-ai/)