# API: scripts, etapas e pastas

_API · Leitura de 5 min · Atualizado 2026-10-22 · https://lanachat.ai/guides/pt/api-scripts/_

Um **script** é uma sequência fixa de etapas para uma criadora: cada etapa é um texto, mídia opcional do Vault, um preço em Stars e uma espera antes da próxima. Scripts ficam em pastas. Um script por criadora pode ser marcado como **first**: ele roda em conversas novas.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/scripts` | Listar scripts (`creator_id=` obrigatório, `folder_id=`, `active=true`) | `can_setup` | Planned |
| POST | `/scripts` | Criar um script com suas etapas | `can_setup` | Planned |
| GET | `/scripts/{id}` | Um script e suas etapas | `can_setup` | Planned |
| PUT | `/scripts/{id}` | Substituir um script (nome, etapas, pasta, contas) | `can_setup` | Planned |
| PATCH | `/scripts/{id}` | Ativar ou desativar, marcar como first, mover para uma pasta | `can_setup` | Planned |
| POST | `/scripts/{id}/duplicate` | Copiar um script (a cópia nunca é first) | `can_setup` | Planned |
| DELETE | `/scripts/{id}` | Deletar um script | `can_setup` | Planned |
| GET | `/scripts/folders` | Pastas de uma criadora (`creator_id=`) | `can_setup` | Planned |
| POST | `/scripts/folders` | Criar uma pasta | `can_setup` | Planned |
| PATCH | `/scripts/folders/{id}` | Renomear uma pasta | `can_setup` | Planned |
| DELETE | `/scripts/folders/{id}` | Deletar uma pasta; seus scripts vão para "No folder" | `can_setup` | Planned |
| POST | `/conversations/{id}/script` | Rodar um script em uma conversa (veja [Conversations](https://lanachat.ai/guides/pt/api-conversations/)) | `can_chat` | Planned |

## O objeto 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 | Descrição |
|---|---|---|
| `id` | string | Começa com `scr_` |
| `creator_id` | string | A criadora cujos fãs recebem o script |
| `name` | string | Nome no Console |
| `goal` | string ou null | Para que serve o script, em suas palavras |
| `folder_id` | string ou null | Pasta do script; `null` é "No folder" |
| `active` | boolean | `false` significa que nunca roda |
| `first` | boolean | `true` significa que roda em conversas novas |
| `account_ids` | array ou null | `null` significa todas as contas Telegram da criadora; array significa só essas (pelo menos uma) |
| `steps` | array | As etapas, em ordem (veja abaixo) |
| `created_at`, `updated_at` | string | ISO 8601, UTC |

Cada etapa tem:

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Começa com `st_` |
| `name` | string | Nome no editor |
| `text` | string | Mensagem que o fã recebe |
| `media` | array de strings | IDs de mídia do [Vault](https://lanachat.ai/guides/pt/api-vault/) da criadora |
| `wait_minutes` | number | Espera antes de enviar esta etapa |
| `pricing.mode` | string | `free`, `vault` (cada mídia pelo preço do Vault) ou `paid` (um preço para toda a etapa) |
| `pricing.stars` | number | Preço em Stars, quando `mode` é `paid` |
| `pricing.discount_stars` | number | Preço opcional menor em Stars |

Definir `first: true` em um script remove essa marca dos outros scripts da criadora.

## Scripts

### Listar scripts

`GET /scripts` · `can_setup`

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `creator_id` | string | Sim | A criadora |
| `folder_id` | string | Não | Só os scripts desta pasta |
| `active` | boolean | Não | `true` lista só scripts ativos |
| `limit`, `cursor` | number, string | Não | [Paginação](https://lanachat.ai/guides/pt/api-overview/) |

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

A resposta é uma página de objetos script em `data`, com `next_cursor`. Sem `creator_id` a API responde `400`.

### Criar um script

`POST /scripts` · `can_setup`

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `creator_id` | string | Sim | A criadora |
| `name` | string | Sim | Nome do script |
| `steps` | array | Sim | Etapas, como no objeto acima (sem `id`) |
| `goal` | string | Não | Para que serve |
| `folder_id` | string | Não | Pasta da mesma criadora |
| `account_ids` | array de strings | Não | Só essas contas; omita 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"
}
```

A resposta é o script novo (`201`), ativo, não first, sem pasta. Um id de mídia do Vault de outra criadora é recusado (`400`).

### Obter um script

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

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

A resposta é o objeto script com todas as suas etapas.

### Substituir um script

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

Envie o script completo: `name`, `steps`, `folder_id` e `account_ids`, como em Criar um script. Etapas omitidas são removidas.

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

A resposta é o script atualizado. Um array vazio em `account_ids` responde `400`: use `null` para todas as contas.

### Ativar, marcar first, mover

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

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `active` | boolean | Não | Ativa ou desativa |
| `first` | boolean | Não | `true` torna o script das conversas novas |
| `folder_id` | string ou null | Não | Move o script; `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}'
```

A resposta é o script atualizado. O script first anterior da criadora perde a marcação `first`.

### Duplicar um 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)"
```

A resposta é a cópia (`201`). A cópia nunca é first.

### Deletar um script

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

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

## Pastas

### Listar pastas

`GET /scripts/folders` · `can_setup`

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `creator_id` | string | Sim | A criadora |

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

### Criar uma pasta

`POST /scripts/folders` · `can_setup`

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `creator_id` | string | Sim | A criadora |
| `name` | string | Sim | Nome da pasta |

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

### Renomear uma pasta

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

### Deletar uma pasta

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

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

Seus scripts são mantidos e movidos para "No folder".

## Rodar um script em uma conversa

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

Inicia um script em uma conversa com um fã: `state` vira `script` até o fim. Corpo, exemplo e regras estão em [Conversations](https://lanachat.ai/guides/pt/api-conversations/).

## Artigos relacionados

- [API LanaChat: início rápido, autenticação e erros](https://lanachat.ai/guides/pt/api-overview/)
- [Scripts: escreva, organize e use-os](https://lanachat.ai/guides/pt/scripts/)
- [Scripts vs. IA: quando o bot segue um script](https://lanachat.ai/guides/pt/scripts-vs-ai/)