FlowBuilder<S> - botmesh

Defined in: flows/FlowBuilder.ts:290 Builder returned by flow. 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`

Constructors

Constructor

new FlowBuilder<S>(trigger): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:297

Parameters

Parameter	Type
`trigger`	`Trigger`

Returns

FlowBuilder<S>

Methods

say()

say(text, opts?): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:304 Send a message. { delay } pauses before sending.

Parameters

Parameter	Type
`text`	`string` \| `DynamicText`<`S`>
`opts?`	`SayStepOptions`

Returns

FlowBuilder<S>

ask()

ask<K, T>(
   text, 
   stateKey, 
   opts?
): FlowBuilder<FlowStateWith<S, K, T>>;

Defined in: flows/FlowBuilder.ts:315 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`<`S`>
`stateKey`	`K`
`opts?`	`AskStepOptions`<`T`>

Returns

FlowBuilder<FlowStateWith<S, K, T>>

do()

do(fn): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:328

Parameters

Parameter	Type
`fn`	`FlowAction`<`S`>

Returns

FlowBuilder<S>

media()

Call Signature

media(
   kind, 
   source, 
   caption?, 
   opts?
): FlowBuilder<S>;

.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` \| `DynamicMediaSource`<`FlowLocation`>
`caption?`	`string`
`opts?`	`FlowMediaOptions`

Returns

FlowBuilder<S>

Call Signature

media(
   kind, 
   source, 
   caption?, 
   opts?
): FlowBuilder<S>;

.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`
`source`	\| `MediaSource` \| `DynamicMediaSource`<`MediaSource`>
`caption?`	`string`
`opts?`	`FlowMediaOptions`

Returns

FlowBuilder<S>

Call Signature

media(source, caption?): FlowBuilder<S>;

.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()

choose<O, K>(
   prompt, 
   options, 
   stateKey?, 
   opts?
): FlowBuilder<FlowStateWith<S, K, Extract<keyof O, string>>>;

Defined in: flows/FlowBuilder.ts:367 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`<`S`>>	-
`K` extends `string`	`"choice"`

Parameters

Parameter	Type
`prompt`	`string`
`options`	`O`
`stateKey?`	`K`
`opts?`	`ChooseStepOptions`

Returns

FlowBuilder<FlowStateWith<S, K, Extract<keyof O, string>>>

use()

Call Signature

use<T>(sub): FlowBuilder<FlowStateMerge<S, T>>;

Defined in: flows/FlowBuilder.ts:400 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<S, T>>

Call Signature

use(sub): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:401 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`

Returns

FlowBuilder<S>

guard()

guard(check, onFail?): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:418 Stop the flow unless check passes. On failure it sends onFail and ends the conversation, or — with { redirect } — jumps to another conversation:

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

Parameters

Parameter	Type
`check`	`FlowGuard`<`S`>
`onFail?`	`GuardFailure`<`S`>

Returns

FlowBuilder<S>

form()

form(definition, opts?): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:447 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`
`opts?`	`FormStepOptions`

Returns

FlowBuilder<S>

Example

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()

delay(d): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:455 Pause the flow ('2s', 1500) before the next step.

Parameters

Parameter	Type
`d`	`FlowDelay`

Returns

FlowBuilder<S>

goto()

goto(target): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:460

Parameters

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

Returns

FlowBuilder<S>

timeout()

timeout(d): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:465

Parameters

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

Returns

FlowBuilder<S>

persistent()

persistent(): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:466

Returns

FlowBuilder<S>

scope()

scope(s): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:467

Parameters

Parameter	Type
`s`	`TriggerScope`

Returns

FlowBuilder<S>

id()

id(explicit): FlowBuilder<S>;

Defined in: flows/FlowBuilder.ts:468

Parameters

Parameter	Type
`explicit`	`string`

Returns

FlowBuilder<S>

compile()

compile(): CompiledFlow;

Defined in: flows/FlowBuilder.ts:470

Returns

CompiledFlow

​Type Parameters

​Constructors

​Constructor

​Parameters

​Returns

​Methods

​say()

​Parameters

​Returns

​ask()

​Type Parameters

​Parameters

​Returns

​do()

​Parameters

​Returns

​media()

​Call Signature

Parameters

Returns

​Call Signature

Parameters

Returns

​Call Signature

Parameters

Returns

​choose()

​Type Parameters

​Parameters

​Returns

​use()

​Call Signature

Type Parameters

Parameters

Returns

​Call Signature

Parameters

Returns

​guard()

​Parameters

​Returns

​form()

​Parameters

​Returns

​Example

​delay()

​Parameters

​Returns

​goto()

​Parameters

​Returns

​timeout()

​Parameters

​Returns

​persistent()

​Returns

​scope()

​Parameters

​Returns

​id()

​Parameters

​Returns

​compile()

​Returns

Type Parameters

Constructors

Constructor

Parameters

Returns

Methods

say()

Parameters

Returns

ask()

Type Parameters

Parameters

Returns

do()

Parameters

Returns

media()

Call Signature

Call Signature

Call Signature

choose()

Type Parameters

Parameters

Returns

use()

Call Signature

Call Signature

guard()

Parameters

Returns

form()

Parameters

Returns

Example

delay()

Parameters

Returns

goto()

Parameters

Returns

timeout()

Parameters

Returns

persistent()

Returns

scope()

Parameters

Returns

id()

Parameters

Returns

compile()

Returns