Interface ConversationControls

Readonlylang

ask

• ask<T>(text: string, opts: SchemaWaitOptions<T>): Promise<T>

  Send text and wait for a text answer. With { schema } (any zod-compatible safeParse) the answer is parsed and the PARSED value is returned (z.coerce.number() → number); a rejected answer re-prompts with otherwise, else the schema's first issue message.

  Type Parameters

  • T

  Parameters

  • text: string
  • opts: SchemaWaitOptions<T>

  Returns Promise<T>

• ask(text: string, opts?: WaitOptions): Promise<string>

  Parameters

  • text: string
  • Optionalopts: WaitOptions

  Returns Promise<string>

waitText

• waitText<T>(opts: SchemaWaitOptions<T>): Promise<T>

  Wait for a text message (no prompt). Accepts { schema } like ask.

  Type Parameters

  • T

  Parameters

  • opts: SchemaWaitOptions<T>

  Returns Promise<T>

• waitText(opts?: WaitOptions): Promise<string>

  Parameters

  • Optionalopts: WaitOptions

  Returns Promise<string>

waitMedia

• waitMedia(types?: WaitMediaType[], opts?: WaitOptions): Promise<RuntimeMessage>

  Parameters

  • Optionaltypes: WaitMediaType[]
  • Optionalopts: WaitOptions

  Returns Promise<RuntimeMessage>

waitLocation

• waitLocation(opts?: WaitOptions): Promise<InboundLocation>

  Wait for a shared location (type: 'location' with a normalized sharedLocation) and resolve with it. Anything else re-prompts with otherwise (default: the localized core.wait.location) and counts against maxAttempts; validate(body, message) can reject a location (message.sharedLocation), e.g. a live one. A location message whose provider could not read valid coordinates is treated as "anything else".

  Parameters

  • Optionalopts: WaitOptions

  Returns Promise<InboundLocation>

choose

• choose(
      prompt: string,
      options: Record<string, string>,
      opts?: WaitOptions,
  ): Promise<string>

  Parameters

  • prompt: string
  • options: Record<string, string>
  • Optionalopts: WaitOptions

  Returns Promise<string>

goto

• goto(name: string, args?: unknown): never

  Parameters

  • name: string
  • Optionalargs: unknown

  Returns never

retry

• retry<T = string>(message?: string): Promise<T>

  Re-run the most recent wait (ask / waitText / waitMedia / choose / waitAny) with its original options (validate, filter, timeout, otherwise, maxAttempts/retries).

  Before waiting again it re-sends the wait's prompt — the ask question or the choose menu — or message instead (for choose, message replaces only the menu header; the numbered options are kept). Waits without a prompt send just message, if given; c.retry('') waits again without sending anything.

  Async conversations (bot.conversation()), and waits made inside the current flow().do() step: resolves with the new value — letra = await c.retry('Solo una letra'). T is that wait's result type: string for ask/waitText/choose, RuntimeMessage for waitMedia/waitAny, InboundLocation for waitLocation.

  Flow steps (flow().do(), a .choose() then action) whose most recent wait belongs to an EARLIER step (.ask(), .choose()): rewinds the flow to that step — it is re-prompted (with message instead of its prompt, when given), its state key gets the new answer, and every following step (including the calling .do()) runs again. It throws a control signal synchronously, so code after c.retry() in the step does not run (like c.end()).

  Budget: each retry counts as one invalid attempt of that wait, shared with validate rejections; reaching the wait's maxAttempts (default 3: the first answer plus 2 retries; retries: N is maxAttempts: N + 1) throws RetriesExceeded (the conversation ends with retriesMessage). A new wait starts a fresh budget. Use maxAttempts: Infinity on the wait for unlimited retries.

  From a c.idle() callback (outside the conversation's flow) it only re-prompts the wait the conversation is parked on — the conversation still receives the answer — and resolves with that answer (undefined if the wait ends another way). If no wait is pending (the conversation is busy between waits, or has not waited yet) it does nothing and resolves undefined; it never re-asks an answered question or rewinds a flow.

  With no previous wait (in the conversation itself) it rejects with RetryUnavailableError. Always await (or return) it: the conversation has one pending-wait slot, so a wait started while an un-awaited retry is still waiting is refused with ConcurrentWaitError (the conversation ends through the error path).

  Type Parameters

  • T = string

  Parameters

  • Optionalmessage: string

  Returns Promise<T>

idle

• idle(duration: string | number, callback: IdleCallback): void

  Arm an inactivity watchdog: callback runs once when duration ('30s', '2m', ms…) passes without an inbound message from this conversation's user; each inbound message reschedules it and re-arms it after it fired. The callback may reply, c.end(farewell) / c.goto(name) to finish the conversation (applied at the pending wait), or c.retry() to re-prompt the pending wait (it cannot start new waits). Other errors go to the bot 'error' event. duration accepts the same formats as bot.onIdle() ('1d', '10 minutes'…) up to 2^31 − 1 ms (about 24.8 days). Calling it again replaces the previous watchdog; it is disarmed automatically when the conversation ends or is aborted. Independent from the wait timeout (which ends the conversation with timeoutMessage).

  Parameters

  • duration: string | number
  • callback: IdleCallback

  Returns void

idleClear

• idleClear(): void

  Disarm the watchdog armed with idle (no-op if none).

  Returns void

t

• t(key: string, params?: TranslateParams): string

  Translate key in the conversation's current language — that of the latest message the user sent to it (so a ctx.setLang() mid-conversation is honoured). Same semantics as ctx.t.

  Parameters

  • key: string
  • Optionalparams: TranslateParams

  Returns string