# Flows

> Crea, publica y envía formularios dentro de WhatsApp

Fuente: https://developers.plazbot.com/sdk/flow/

### Introducción

El módulo **Flow** gestiona los WhatsApp Flows del workspace: formularios de varias pantallas que el contacto llena sin salir de WhatsApp (reservar una cita, registrarse, una encuesta). Son los mismos Flows de **WhatsApp** > **Flows** en Plazbot: lo que creas aquí aparece en el panel y en el editor de automatizaciones. Disponible desde la versión **2.4.0**.

### Inicialización

```ts Plazbot (recomendado)
import { Plazbot } from 'plazbot';

const plazbot = new Plazbot({
workspaceId: "YOUR_WORKSPACE_ID",
apiKey: "YOUR_API_KEY",
zone: "LA"
});

// Usar: plazbot.flow.list()
```

```ts Flow individual
import { Flow } from 'plazbot';

const flow = new Flow({
workspaceId: "YOUR_WORKSPACE_ID",
apiKey: "YOUR_API_KEY",
zone: "LA"
});
```

---

### Listar y obtener

```ts
const flows = await plazbot.flow.list();
const flow = await plazbot.flow.get("flo_...");   // incluye flowJson
```

---

### Crear un Flow

El JSON del Flow usa el formato de Meta (`version` y `screens`). El Flow se crea en Meta como **borrador**. Si Meta encuentra errores en el JSON, el Flow se guarda igual y los errores vienen en `validationError`.

```ts
const { id, validationError } = await plazbot.flow.create({
name: "Reservar cita",
categories: ["APPOINTMENT_BOOKING"],
flowJson: {
  version: "7.0",
  screens: [/* pantallas del Flow */]
}
});

if (validationError) console.log("Revisa el JSON:", validationError);
```

| Campo | Descripción |
|-------|-------------|
| `name` | Nombre del Flow. |
| `flowJson` | JSON del Flow en formato de Meta. |
| `categories` | `SIGN_UP`, `SIGN_IN`, `APPOINTMENT_BOOKING`, `LEAD_GENERATION`, `CONTACT_US`, `CUSTOMER_SUPPORT`, `SURVEY` u `OTHER`. Por defecto `OTHER`. |
| `number` / `numberId` | Número dueño del Flow. Opcional si el workspace tiene un solo número. |
| `description` | Descripción interna. |
| `dataExchangeConfig` | Configuración del endpoint de intercambio de datos, si el Flow lo usa. |

---

### Probar, publicar y editar

```ts
// Un borrador se envía en modo de prueba: úsalo con tu propio número
await plazbot.flow.send({
flowId: id,
to: "51912345678",
body: "Reserva tu cita aquí",
cta: "Reservar"          // texto del botón
});

await plazbot.flow.update(id, { flowJson: nuevoJson }); // solo borradores; lo que no pases se mantiene
await plazbot.flow.publish(id);                          // ya no se puede editar

// Para cambiar un Flow publicado: duplícalo, edita la copia y publícala
const copy = await plazbot.flow.duplicate(id);
```

`send()` acepta también `header` y `footer`. Enviar un Flow es un mensaje libre: solo sale dentro de las 24 horas desde el último mensaje del contacto, y el contacto debe existir en el workspace.

---

### Activar, desactivar y borrar

```ts
await plazbot.flow.setActive(id, false);               // se oculta del editor de automatizaciones
await plazbot.flow.delete(id);                         // solo en Plazbot
await plazbot.flow.delete(id, { alsoInMeta: true });   // también en Meta (los publicados se deprecan)
```

### Respuestas del Flow

Lo que llena el contacto llega como un mensaje del contacto, en el chat y en tus [webhooks](https://developers.plazbot.com/whatsapp/recibir-mensajes), y se puede usar en las automatizaciones.

### Errores

Los métodos lanzan `PlazbotApiError` (con `code` y `message`) cuando la API o Meta rechazan la operación.