ConversationForm

^{ref / conversations / ConversationForm}

A container for form building utilities.

Each method on this class represents a differnt type of form field which can validate context objects and extract data from it.

^Source

Type Parameters

C

C extends Context

Constructors

ConversationForm(conversation: { wait: (opts: { maxMilliseconds?: number; collationKey?: string }) => Promise<C>; skip: (opts: { next?: boolean }) => Promise<never> });

Constructs a new form based on wait and skip callbacks

^Source

Methods

build

// Overload 1
build<T, R>(builder: FormBuilderWithReason<C, T, R>): Promise<T>;
// Overload 2
build<T, R>(builder: FormBuilder<C, T>): Promise<T>;

Generic form field that can be used to build any other type of form field. This is heavily used internally.

Most likely, you will not need this because there is a more convenient option. However, you can still use it if the type of form field you need is not supported out of the box.

^Source

text

text(options?: FormOptions<C, string>);

Form field that checks if the incoming update contains a message or channel post with text, and returns this text as string. Does not check for captions.

Accepts an optional options object that lets you perform actions when text is received, when a non-text update is received, and more.

^Source

number

number(options?: FormOptions<C, number>);

Form field that checks if the incoming update contains a message or channel post with text that can be parsed to a number, and returns this number. Does not check captions.

The conversion to number uses parseFloat.

Accepts an optional options object that lets you perform actions when a number is received, when a non-number update is received, and more.

^Source

int

int(options?: FormOptions<C, number> & { radix?: number });

Form field that checks if the incoming update contains a message or channel post with text that can be parsed to an integer, and returns this integer as a number. Does not check for captions.

The conversion to number uses parseInt.

Accepts an optional options object that lets you specify the radix to use as well as perform actions when a number is received, when a non-number update is received, and more.

^Source

select

select<E extends string>(entries: E[], options?: FormOptions<C, E>);

Form field that checks if the incoming update contains a message or channel post with one of several predefined strings, and returns the actual text as string. Does not check captions.

This is especially useful when working with custom keyboards.

const keyboard = new Keyboard()
  .text("A").text("B")
  .text("C").text("D")
  .oneTime()
await ctx.reply("A, B, C, or D?", { reply_markup: keyboard })
const answer = await conversation.form.select(["A", "B", "C", "D"], {
  otherwise: ctx => ctx.reply("Please use one of the buttons!")
})
switch (answer) {
  case "A":
  case "B":
  case "C":
  case "D":
  // ...
}

Accepts an optional options object that lets you perform actions when text is received, when a non-text update is received, and more.

^Source

entity

entity<M extends MessageEntity>(type: M["type"] | M["type"][], options?: FormOptions<C, MessageEntity & { text: string }>);

Form field that checks if the incoming update contains a message or channel post with a given type of message entity, and returns this entity. The form field relies on ctx.entities() for data extraction, so both texts and captions are checked.

Accepts an optional options object that lets you perform actions when text is received, when a non-text update is received, and more.

^Source

animation

animation(options?: FormOptions<C, Animation>);

Form field that checks if the incoming update contains a message or channel post with an animation, and returns the received animation object.

Accepts an optional options object that lets you perform actions when an animation is received, when a non-animation update is received, and more.

^Source

audio

audio(options?: FormOptions<C, Audio>);

Form field that checks if the incoming update contains a message or channel post with an audio message, and returns the received audio object.

Accepts an optional options object that lets you perform actions when an audio message is received, when a non-audio update is received, and more.

^Source

document

document(options?: FormOptions<C, Document>);

Form field that checks if the incoming update contains a message or channel post with a document message, and returns the received document object.

Accepts an optional options object that lets you perform actions when a document message is received, when a non-document update is received, and more.

^Source

paidMedia

paidMedia(options?: FormOptions<C, PaidMediaInfo>);

Form field that checks if the incoming update contains a message or channel post with paid media, and returns the received paid media object.

Accepts an optional options object that lets you perform actions when a paid media message is received, when a non-paid media update is received, and more.

^Source

photo

photo(options?: FormOptions<C, PhotoSize[]>);

Form field that checks if the incoming update contains a message or channel post with a photo, and returns the received array of PhotoSize objects.

Accepts an optional options object that lets you perform actions when a photo is received, when a non-photo update is received, and more.

^Source

sticker

sticker(options?: FormOptions<C, Sticker>);

Form field that checks if the incoming update contains a message or channel post with a sticker, and returns the received sticker object.

Accepts an optional options object that lets you perform actions when a sticker is received, when a non-sticker update is received, and more.

^Source

story

story(options?: FormOptions<C, Story>);

Form field that checks if the incoming update contains a message or channel post with a story, and returns the received story object.

Accepts an optional options object that lets you perform actions when a story is received, when a non-story update is received, and more.

^Source

video

video(options?: FormOptions<C, Video>);

Form field that checks if the incoming update contains a message or channel post with a video, and returns the received video object.

Accepts an optional options object that lets you perform actions when a video is received, when a non-video update is received, and more.

^Source

video_note

video_note(options?: FormOptions<C, VideoNote>);

Form field that checks if the incoming update contains a message or channel post with a video note, and returns the received video note object.

Accepts an optional options object that lets you perform actions when a video note is received, when a non-video note update is received, and more.

^Source

voice

voice(options?: FormOptions<C, Voice>);

Form field that checks if the incoming update contains a message or channel post with a voice message, and returns the received voice object.

Accepts an optional options object that lets you perform actions when a voice message is received, when a non-voice message update is received, and more.

^Source

contact

contact(options?: FormOptions<C, Contact>);

Form field that checks if the incoming update contains a message or channel post with a contact, and returns the received contact object.

Accepts an optional options object that lets you perform actions when a contact is received, when a non-contact update is received, and more.

^Source

dice

dice(options?: FormOptions<C, Dice>);

Form field that checks if the incoming update contains a message or channel post with dice, and returns the received dice object.

Accepts an optional options object that lets you perform actions when dice are received, when a non-dice update is received, and more.

^Source

game

game(options?: FormOptions<C, Game>);

Form field that checks if the incoming update contains a message or channel post with a game, and returns the received game object.

Accepts an optional options object that lets you perform actions when a game is received, when a non-game update is received, and more.

^Source

poll

poll(options?: FormOptions<C, Poll>);

Form field that checks if the incoming update contains a message or channel post with a poll, and returns the received poll object.

Accepts an optional options object that lets you perform actions when a poll is received, when a non-poll update is received, and more.

^Source

venue

venue(options?: FormOptions<C, Venue>);

Form field that checks if the incoming update contains a message or channel post with a venue, and returns the received venue object.

Accepts an optional options object that lets you perform actions when a venue is received, when a non-venue update is received, and more.

^Source

location

location(options?: FormOptions<C, Location>);

Form field that checks if the incoming update contains a message or channel post with a location, and returns the received location object.

Accepts an optional options object that lets you perform actions when a location is received, when a non-location update is received, and more.

^Source

media

media(options?: FormOptions<C, PhotoSize[] | Video>);

Form field that checks if the incoming update contains a message or channel post with a photo or video, and returns the received media object.

Accepts an optional options object that lets you perform actions when a media is received, when a non-media update is received, and more.

^Source

file

file(options?: FormOptions<C, File>);

Form field that checks if the incoming update contains a message or channel post with a file, calls await ctx.getFile(), and returns the received file object.

Accepts an optional options object that lets you perform actions when a file is received, when a non-file update is received, and more.

^Source