Class CallbackContext<UserData, ChatData, BotData>

Context object passed to handler callbacks, error handlers, and job callbacks.

Remarks

Context state property names (context.user_data, context.chat_data, context.bot_data, context.args, context.job_queue) use consistent snake_case naming.

Example

async function startCallback(update: Update, context: CallbackContext) {
  const name = update.effective_user?.first_name ?? "there";
  context.user_data.visited = true;
  await context.bot.sendMessage({
    chat_id: update.effective_chat!.id,
    text: `Hello ${name}!`,
  });
}

Type Parameters

UserData extends Record<string, unknown> = Record<string, unknown>
Custom type definition for user-level persisted state.
ChatData extends Record<string, unknown> = Record<string, unknown>
Custom type definition for chat-level persisted state.
BotData extends Record<string, unknown> = Record<string, unknown>
Custom type definition for bot-level persisted state.

Index

Constructors

constructor

new CallbackContext<
    UserData extends Record<string, unknown> = Record<string, unknown>,
    ChatData extends Record<string, unknown> = Record<string, unknown>,
    BotData extends Record<string, unknown> = Record<string, unknown>,
>(
    options: {
        args?: string[];
        bot: Bot;
        bot_data?: BotData;
        botData?: BotData;
        chat_data?: ChatData;
        chatData?: ChatData;
        conversationManager?: AsyncConversationManager;
        error?: Error;
        job?: Job<unknown>;
        job_queue?: JobQueue;
        matches?: RegExpMatchArray[];
        scheduler?: JobQueue;
        task?: Job<unknown>;
        update?: Update;
        user_data?: UserData;
        userData?: UserData;
    },
): CallbackContext<UserData, ChatData, BotData>
Creates a new CallbackContext instance.
Type Parameters
- UserData extends Record<string, unknown> = Record<string, unknown>
  Custom type definition for user-level persisted state.
- ChatData extends Record<string, unknown> = Record<string, unknown>
  Custom type definition for chat-level persisted state.
- BotData extends Record<string, unknown> = Record<string, unknown>
  Custom type definition for bot-level persisted state.
Parameters
- options: {
      args?: string[];
      bot: Bot;
      bot_data?: BotData;
      botData?: BotData;
      chat_data?: ChatData;
      chatData?: ChatData;
      conversationManager?: AsyncConversationManager;
      error?: Error;
      job?: Job<unknown>;
      job_queue?: JobQueue;
      matches?: RegExpMatchArray[];
      scheduler?: JobQueue;
      task?: Job<unknown>;
      update?: Update;
      user_data?: UserData;
      userData?: UserData;
  }
  Initialization options for context properties.
Returns CallbackContext<UserData, ChatData, BotData>

Properties

`Optional`args

args?: string[]

Positional arguments parsed from a command message.

`Readonly`bot

bot: Bot

The Bot client instance executing this handler.

`Optional`botData

botData?: BotData

Global bot-level persistent or memory storage object.

`Optional`chatData

chatData?: ChatData

Per-chat persistent or memory storage object.

conversation

conversation: ConversationContextHelper

Linear async conversation helper instance.

`Optional`error

error?: Error

The caught exception / error when invoked inside an error handler.

`Optional`matches

matches?: RegExpMatchArray[]

RegExp match arrays populated by filters matching regular expressions.

`Optional`menu

menu?: MenuContextControl

Interactive menu navigation and live update helper when invoked inside a menu callback.

`Optional`scheduler

scheduler?: JobQueue

Background task scheduler and timer engine.

`Optional`task

task?: Job<unknown>

The current background task/job being executed (when invoked from the scheduler).

`Optional` `Readonly`update

update?: Update

The Update that triggered this handler invocation, if applicable.

`Optional`userData

userData?: UserData

Per-user persistent or memory storage object.

Accessors

bot_data

get bot_data(): BotData | undefined

Returns BotData | undefined
set bot_data(val: BotData | undefined): void
Parameters
- val: BotData | undefined
Returns void

chat_data

get chat_data(): ChatData | undefined

Returns ChatData | undefined
set chat_data(val: ChatData | undefined): void
Parameters
- val: ChatData | undefined
Returns void

job

get job(): Job<unknown> | undefined

Returns Job<unknown> | undefined
set job(val: Job<unknown> | undefined): void
Parameters
- val: Job<unknown> | undefined
Returns void

job_queue

get job_queue(): JobQueue | undefined

Returns JobQueue | undefined
set job_queue(val: JobQueue | undefined): void
Parameters
- val: JobQueue | undefined
Returns void

user_data

get user_data(): UserData | undefined

Returns UserData | undefined
set user_data(val: UserData | undefined): void
Parameters
- val: UserData | undefined
Returns void

Methods

answerCallbackQuery

answerCallbackQuery(
options?: Omit<AnswerCallbackQueryOptions, "callback_query_id">,
): Promise<boolean>
Convenience shortcut to answer the active callback query.
Parameters
- options: Omit<AnswerCallbackQueryOptions, "callback_query_id"> = {}
  Additional answer options (e.g. text notification, alert).
Returns Promise<boolean>
true on success.

deleteMessage

deleteMessage(messageId?: number): Promise<boolean>
Convenience shortcut to delete a message in the current chat.
Parameters
- OptionalmessageId: number
  Identifier of the message to delete (defaults to current effective_message).
Returns Promise<boolean>
true on success.

editMessageText

editMessageText(
text: string,
options?: Omit<EditMessageTextOptions, "chat_id" | "message_id" | "text">,
): Promise<boolean | Message>
Convenience shortcut to edit the text of the current message.
Parameters
- text: string
  New message text.
- options: Omit<EditMessageTextOptions, "chat_id" | "message_id" | "text"> = {}
  Additional text editing options.
Returns Promise<boolean | Message>
The edited Message or true.

reply

reply(
text: string,
options?: Omit<SendMessageOptions, "chat_id" | "text">,
): Promise<Message>
Convenience shortcut to send a text reply to the current chat.
Parameters
- text: string
  Message text to send.
- options: Omit<SendMessageOptions, "chat_id" | "text"> = {}
  Additional parameters for sending message.
Returns Promise<Message>
The sent Message.
Example
```
await context.reply("Hello there!");
```

replyWithAudio

replyWithAudio(
audio: string | InputFile,
options?: Omit<SendAudioOptions, "chat_id" | "audio">,
): Promise<Message>
Convenience shortcut to send an audio file to the current chat.
Parameters
- audio: string | InputFile
  File ID, URL, or InputFile.
- options: Omit<SendAudioOptions, "chat_id" | "audio"> = {}
  Additional audio options.
Returns Promise<Message>
The sent Message.

replyWithDocument

replyWithDocument(
document: string | InputFile,
options?: Omit<SendDocumentOptions, "chat_id" | "document">,
): Promise<Message>
Convenience shortcut to send a document/file to the current chat.
Parameters
- document: string | InputFile
  File ID, URL, or InputFile.
- options: Omit<SendDocumentOptions, "chat_id" | "document"> = {}
  Additional document options.
Returns Promise<Message>
The sent Message.

replyWithHTML

replyWithHTML(
htmlText: string,
options?: Omit<SendMessageOptions, "chat_id" | "text" | "parse_mode">,
): Promise<Message>
Convenience shortcut to send an HTML-formatted message to the current chat.
Parameters
- htmlText: string
  HTML string content.
- options: Omit<SendMessageOptions, "chat_id" | "text" | "parse_mode"> = {}
  Additional message options.
Returns Promise<Message>
The sent Message.

replyWithMarkdown

replyWithMarkdown(
markdownText: string,
options?: Omit<SendMessageOptions, "chat_id" | "text" | "parse_mode">,
): Promise<Message>
Convenience shortcut to send a MarkdownV2-formatted message to the current chat.
Parameters
- markdownText: string
  MarkdownV2 string content.
- options: Omit<SendMessageOptions, "chat_id" | "text" | "parse_mode"> = {}
  Additional message options.
Returns Promise<Message>
The sent Message.

replyWithPhoto

replyWithPhoto(
photo: string | InputFile,
options?: Omit<SendPhotoOptions, "chat_id" | "photo">,
): Promise<Message>
Convenience shortcut to send a photo to the current chat.
Parameters
- photo: string | InputFile
  File ID, URL, or InputFile.
- options: Omit<SendPhotoOptions, "chat_id" | "photo"> = {}
  Additional photo options.
Returns Promise<Message>
The sent Message.

replyWithVideo

replyWithVideo(
video: string | InputFile,
options?: Omit<SendVideoOptions, "chat_id" | "video">,
): Promise<Message>
Convenience shortcut to send a video to the current chat.
Parameters
- video: string | InputFile
  File ID, URL, or InputFile.
- options: Omit<SendVideoOptions, "chat_id" | "video"> = {}
  Additional video options.
Returns Promise<Message>
The sent Message.

Class CallbackContext<UserData, ChatData, BotData>

Remarks

Example

Type Parameters

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns CallbackContext<UserData, ChatData, BotData>

Properties

Optionalargs

Readonlybot

OptionalbotData

OptionalchatData

conversation

Optionalerror

Optionalmatches

Optionalmenu

Optionalscheduler

Optionaltask

Optional Readonlyupdate

OptionaluserData

Accessors

bot_data

Returns BotData | undefined

Parameters

Returns void

chat_data

Returns ChatData | undefined

Parameters

Returns void

job

Returns Job<unknown> | undefined

Parameters

Returns void

job_queue

Returns JobQueue | undefined

Parameters

Returns void

user_data

Returns UserData | undefined

Parameters

Returns void

Methods

answerCallbackQuery

Parameters

Returns Promise<boolean>

deleteMessage

Parameters

Returns Promise<boolean>

editMessageText

Parameters

Returns Promise<boolean | Message>

reply

Parameters

Returns Promise<Message>

Example

replyWithAudio

Parameters

Returns Promise<Message>

replyWithDocument

Parameters

Returns Promise<Message>

replyWithHTML

Parameters

Returns Promise<Message>

replyWithMarkdown

Parameters

Returns Promise<Message>

replyWithPhoto

Parameters

Returns Promise<Message>

replyWithVideo

Parameters

Returns Promise<Message>

`Optional`args

`Readonly`bot

`Optional`botData

`Optional`chatData

`Optional`error

`Optional`matches

`Optional`menu

`Optional`scheduler

`Optional`task

`Optional` `Readonly`update

`Optional`userData