> ## Documentation Index
> Fetch the complete documentation index at: https://botmesh.afaya.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# FlowBuilder<S>

> Class exported by @botmesh/core.

Defined in: [flows/FlowBuilder.ts:290](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L290)

Builder returned by [flow](https://botmesh.afaya.com.co/api/core/functions/flow.md). Chain steps (`say`, `ask`, `choose`, `do`,
`media`, `form`, `use`, `goto`…) and register the flow with `bot.use()`. Every method returns
the builder, and the type of `c.state` grows with each `ask`, `choose` and `use`.

## Type Parameters

| Type Parameter | Default type |
| - | - |
|  `S` *extends* `object` | [`EmptyFlowState`](https://botmesh.afaya.com.co/api/core/type-aliases/EmptyFlowState) |

## Constructors

### Constructor

```ts theme={null}
new FlowBuilder<S>(trigger): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:297](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L297)

#### Parameters

| Parameter | Type |
| - | - |
| `trigger` | [`Trigger`](https://botmesh.afaya.com.co/api/core/type-aliases/Trigger) |

#### Returns

`FlowBuilder`\<`S`>

## Methods

### say()

```ts theme={null}
say(text, opts?): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:304](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L304)

Send a message. `{ delay }` pauses before sending.

#### Parameters

| Parameter | Type |
| - | - |
| `text` | `string` \| [`DynamicText`](https://botmesh.afaya.com.co/api/core/type-aliases/DynamicText)\<`S`> |
| `opts?` | [`SayStepOptions`](https://botmesh.afaya.com.co/api/core/interfaces/SayStepOptions) |

#### Returns

`FlowBuilder`\<`S`>

***

### ask()

```ts theme={null}
ask<K, T>(
   text, 
   stateKey, 
   opts?
): FlowBuilder<FlowStateWith<S, K, T>>;
```

Defined in: [flows/FlowBuilder.ts:315](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L315)

Ask a question and store the answer in `c.state[stateKey]`. With `{ schema }` the parsed
value is stored and typed: `.ask('¿Edad?', 'edad', { schema: z.coerce.number() })` →
`c.state.edad: number`.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
|  `K` *extends* `string` | - |
|  `T` | `string` |

#### Parameters

| Parameter | Type |
| - | - |
| `text` | `string` \| [`DynamicText`](https://botmesh.afaya.com.co/api/core/type-aliases/DynamicText)\<`S`> |
| `stateKey` | `K` |
| `opts?` | [`AskStepOptions`](https://botmesh.afaya.com.co/api/core/interfaces/AskStepOptions)\<`T`> |

#### Returns

`FlowBuilder`\<[`FlowStateWith`](https://botmesh.afaya.com.co/api/core/type-aliases/FlowStateWith)\<`S`, `K`, `T`>>

***

### do()

```ts theme={null}
do(fn): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:328](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L328)

#### Parameters

| Parameter | Type |
| - | - |
| `fn` | [`FlowAction`](https://botmesh.afaya.com.co/api/core/type-aliases/FlowAction)\<`S`> |

#### Returns

`FlowBuilder`\<`S`>

***

### media()

#### Call Signature

```ts theme={null}
media(
   kind, 
   source, 
   caption?, 
   opts?
): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:341](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L341)

Send media. `kind` is one of `image | video | audio | voice | document | sticker | location`:

```ts theme={null}
.media('image', 'https://…/menu.png', 'Nuestro menú')
.media('document', './factura.pdf', 'Tu factura', { filename: 'factura.pdf' })
.media('location', { lat: 4.71, lng: -74.07 }, 'Bogotá')
```

The legacy two-argument form `.media(source, caption?)` sends an image.

##### Parameters

| Parameter | Type |
| - | - |
| `kind` | `"location"` |
| `source` | \| [`FlowLocation`](https://botmesh.afaya.com.co/api/core/interfaces/FlowLocation) \| [`DynamicMediaSource`](https://botmesh.afaya.com.co/api/core/type-aliases/DynamicMediaSource)\<[`FlowLocation`](https://botmesh.afaya.com.co/api/core/interfaces/FlowLocation)> |
| `caption?` | `string` |
| `opts?` | [`FlowMediaOptions`](https://botmesh.afaya.com.co/api/core/interfaces/FlowMediaOptions) |

##### Returns

`FlowBuilder`\<`S`>

#### Call Signature

```ts theme={null}
media(
   kind, 
   source, 
   caption?, 
   opts?
): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:342](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L342)

Send media. `kind` is one of `image | video | audio | voice | document | sticker | location`:

```ts theme={null}
.media('image', 'https://…/menu.png', 'Nuestro menú')
.media('document', './factura.pdf', 'Tu factura', { filename: 'factura.pdf' })
.media('location', { lat: 4.71, lng: -74.07 }, 'Bogotá')
```

The legacy two-argument form `.media(source, caption?)` sends an image.

##### Parameters

| Parameter | Type |
| - | - |
| `kind` | [`FlowFileMediaKind`](https://botmesh.afaya.com.co/api/core/type-aliases/FlowFileMediaKind) |
| `source` | \| [`MediaSource`](https://botmesh.afaya.com.co/api/core/type-aliases/MediaSource) \| [`DynamicMediaSource`](https://botmesh.afaya.com.co/api/core/type-aliases/DynamicMediaSource)\<[`MediaSource`](https://botmesh.afaya.com.co/api/core/type-aliases/MediaSource)> |
| `caption?` | `string` |
| `opts?` | [`FlowMediaOptions`](https://botmesh.afaya.com.co/api/core/interfaces/FlowMediaOptions) |

##### Returns

`FlowBuilder`\<`S`>

#### Call Signature

```ts theme={null}
media(source, caption?): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:343](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L343)

Send media. `kind` is one of `image | video | audio | voice | document | sticker | location`:

```ts theme={null}
.media('image', 'https://…/menu.png', 'Nuestro menú')
.media('document', './factura.pdf', 'Tu factura', { filename: 'factura.pdf' })
.media('location', { lat: 4.71, lng: -74.07 }, 'Bogotá')
```

The legacy two-argument form `.media(source, caption?)` sends an image.

##### Parameters

| Parameter | Type |
| - | - |
| `source` | `string` |
| `caption?` | `string` |

##### Returns

`FlowBuilder`\<`S`>

***

### choose()

```ts theme={null}
choose<O, K>(
   prompt, 
   options, 
   stateKey?, 
   opts?
): FlowBuilder<FlowStateWith<S, K, Extract<keyof O, string>>>;
```

Defined in: [flows/FlowBuilder.ts:367](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L367)

Present a numbered menu and capture the selection. The picked option KEY is stored in
`c.state[stateKey]` (defaults to `c.state.choice`), so a later `.say`/`.do` can read it.
An option's `then` sub-flow runs inline and returns here (sharing `c.state`); its `goto`
leaves the flow for another conversation.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
|  `O` *extends* `Record`\<`string`, [`ChooseOption`](https://botmesh.afaya.com.co/api/core/type-aliases/ChooseOption)\<`S`>> | - |
|  `K` *extends* `string` | `"choice"` |

#### Parameters

| Parameter | Type |
| - | - |
| `prompt` | `string` |
| `options` | `O` |
| `stateKey?` | `K` |
| `opts?` | [`ChooseStepOptions`](https://botmesh.afaya.com.co/api/core/interfaces/ChooseStepOptions) |

#### Returns

`FlowBuilder`\<[`FlowStateWith`](https://botmesh.afaya.com.co/api/core/type-aliases/FlowStateWith)\<`S`, `K`, `Extract`\<keyof `O`, `string`>>>

***

### use()

#### Call Signature

```ts theme={null}
use<T>(sub): FlowBuilder<FlowStateMerge<S, T>>;
```

Defined in: [flows/FlowBuilder.ts:400](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L400)

Run another flow inline, then come back and continue with the next step. The sub-flow
shares `c.state`, so whatever it captures is visible here (and typed: the builder's
state merges the sub-flow's). The sub-flow is snapshotted at this call.

##### Type Parameters

| Type Parameter |
| - |
|  `T` *extends* `object` |

##### Parameters

| Parameter | Type |
| - | - |
| `sub` | `FlowBuilder`\<`T`> |

##### Returns

`FlowBuilder`\<[`FlowStateMerge`](https://botmesh.afaya.com.co/api/core/type-aliases/FlowStateMerge)\<`S`, `T`>>

#### Call Signature

```ts theme={null}
use(sub): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:401](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L401)

Run another flow inline, then come back and continue with the next step. The sub-flow
shares `c.state`, so whatever it captures is visible here (and typed: the builder's
state merges the sub-flow's). The sub-flow is snapshotted at this call.

##### Parameters

| Parameter | Type |
| - | - |
| `sub` | [`CompiledFlow`](https://botmesh.afaya.com.co/api/core/interfaces/CompiledFlow) |

##### Returns

`FlowBuilder`\<`S`>

***

### guard()

```ts theme={null}
guard(check, onFail?): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:418](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L418)

Stop the flow unless `check` passes. On failure it sends `onFail` and ends the conversation,
or — with `{ redirect }` — jumps to another conversation:

```ts theme={null}
.guard(() => esHorarioLaboral(), 'Fuera de horario, vuelve mañana')
.guard(async (ctx) => isAdmin(ctx.sender), { redirect: 'no-permiso' })
```

#### Parameters

| Parameter | Type |
| - | - |
| `check` | [`FlowGuard`](https://botmesh.afaya.com.co/api/core/type-aliases/FlowGuard)\<`S`> |
| `onFail?` | [`GuardFailure`](https://botmesh.afaya.com.co/api/core/type-aliases/GuardFailure)\<`S`> |

#### Returns

`FlowBuilder`\<`S`>

***

### form()

```ts theme={null}
form(definition, opts?): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:447](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L447)

Collect a typed form. On providers with `capabilities.forms === 'native'`
(WhatsApp Cloud API → WhatsApp Flows) it sends one native form and waits for
its submission; elsewhere it asks field by field. Either way the validated
answers are stored in `c.state[opts.stateKey ?? definition.id]`.
The definition is checked here: a malformed one throws a `TypeError`.

#### Parameters

| Parameter | Type |
| - | - |
| `definition` | [`FormDefinition`](https://botmesh.afaya.com.co/api/core/interfaces/FormDefinition) |
| `opts?` | [`FormStepOptions`](https://botmesh.afaya.com.co/api/core/interfaces/FormStepOptions) |

#### Returns

`FlowBuilder`\<`S`>

#### Example

```ts theme={null}
flow('registro')
  .form({ id: 'signup', title: 'Registro', fields: [
    { type: 'text', name: 'name', label: 'Nombre' },
    { type: 'email', name: 'email', label: 'Correo' },
    { type: 'select', name: 'plan', label: 'Plan', options: { basic: 'Básico', pro: 'Pro' } },
  ] })
  .say((_ctx, c) => `Gracias ${(c.state.signup as { name: string }).name}`)
```

***

### delay()

```ts theme={null}
delay(d): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:455](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L455)

Pause the flow (`'2s'`, `1500`) before the next step.

#### Parameters

| Parameter | Type |
| - | - |
| `d` | [`FlowDelay`](https://botmesh.afaya.com.co/api/core/type-aliases/FlowDelay) |

#### Returns

`FlowBuilder`\<`S`>

***

### goto()

```ts theme={null}
goto(target): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:460](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L460)

#### Parameters

| Parameter | Type |
| - | - |
| `target` | `string` \| `FlowBuilder`\<`object`> |

#### Returns

`FlowBuilder`\<`S`>

***

### timeout()

```ts theme={null}
timeout(d): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:465](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L465)

#### Parameters

| Parameter | Type |
| - | - |
| `d` | `string` \| `number` |

#### Returns

`FlowBuilder`\<`S`>

***

### persistent()

```ts theme={null}
persistent(): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:466](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L466)

#### Returns

`FlowBuilder`\<`S`>

***

### scope()

```ts theme={null}
scope(s): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:467](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L467)

#### Parameters

| Parameter | Type |
| - | - |
| `s` | [`TriggerScope`](https://botmesh.afaya.com.co/api/core/type-aliases/TriggerScope) |

#### Returns

`FlowBuilder`\<`S`>

***

### id()

```ts theme={null}
id(explicit): FlowBuilder<S>;
```

Defined in: [flows/FlowBuilder.ts:468](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L468)

#### Parameters

| Parameter | Type |
| - | - |
| `explicit` | `string` |

#### Returns

`FlowBuilder`\<`S`>

***

### compile()

```ts theme={null}
compile(): CompiledFlow;
```

Defined in: [flows/FlowBuilder.ts:470](https://github.com/andresayac/botmesh/blob/main/packages/core/src/flows/FlowBuilder.ts#L470)

#### Returns

[`CompiledFlow`](https://botmesh.afaya.com.co/api/core/interfaces/CompiledFlow)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.