telega/reply

reply provides a convenient way to send messages to the active chat. It uses the Context object to access the chat ID and other necessary information.

Ephemeral messages (Bot API 10.3)

In a group chat a message can be addressed to a single user — nobody else sees it. with_ephemeral_text and with_ephemeral_markup aim at the user of the current update, wiring callback_query_id in when that update is a callback query, so the message appears under the pressed button:

let assert Ok(_) = reply.with_ephemeral_text(ctx, "Booked — only you see this")

with_ephemeral takes explicit parameters instead, built with ephemeral_parameters or types.new_ephemeral_message_parameters:

reply.with_ephemeral(
  ctx:,
  text: "Shown in place of the original message",
  parameters: types.EphemeralMessageParameters(
    ..reply.ephemeral_parameters(ctx),
    replace_callback_query_message: Some(True),
  ),
)

Every send* parameter record carries the same optional ephemeral_message_parameters field, so photos, videos, stickers and the rest can be ephemeral too:

api.send_photo(
  client,
  parameters: types.SendPhotoParameters(
    ..parameters,
    ephemeral_message_parameters: Some(reply.ephemeral_parameters(ctx)),
  ),
)

The sent Message carries an ephemeral_message_id; pass it to api.edit_ephemeral_message_* / api.delete_ephemeral_message to change or remove the message later. Under handle_bot_with_reply the first eligible send of an update is answered through the webhook response itself and comes back as a stub Message without that id — wrap such a call in webhook_reply.without_claim when you need the real one.

Values

answer_callback_query

</>

pub fn answer_callback_query(
  ctx ctx: bot.Context(session, error, dependencies),
  parameters parameters: types.AnswerCallbackQueryParameters,
) -> Result(Bool, error.TelegaError)

Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. On success, True is returned.

Official reference: https://core.telegram.org/bots/api#answercallbackquery

edit_text

</>

pub fn edit_text(
  ctx ctx: bot.Context(session, error, dependencies),
  parameters parameters: types.EditMessageTextParameters,
) -> Result(types.Message, error.TelegaError)

Use this method to edit text and game messages. On success, if the edited message is not an inline message, the edited Message is returned, otherwise True is returned.

If parameters.parse_mode is None, the client’s default parse mode (set via client.set_default_parse_mode) is used.

Official reference: https://core.telegram.org/bots/api#editmessagetext

edit_text_formatted

</>

pub fn edit_text_formatted(
  ctx ctx: bot.Context(session, error, dependencies),
  message_id message_id: Int,
  formatted formatted: format.FormattedText,
) -> Result(types.Message, error.TelegaError)

Use this method to edit formatted text messages.

Official reference: https://core.telegram.org/bots/api#editmessagetext

ephemeral_parameters

</>

pub fn ephemeral_parameters(
  ctx ctx: bot.Context(session, error, dependencies),
) -> types.EphemeralMessageParameters

Ephemeral parameters aimed at the user of the current update (Bot API 10.3).

When the update is a callback query, its id is wired in, so Telegram can attach the ephemeral message to the pressed button. Adjust the result with a record update to show the message in place of the original one:

types.EphemeralMessageParameters(
  ..reply.ephemeral_parameters(ctx),
  replace_callback_query_message: Some(True),
)

forward

</>

pub fn forward(
  ctx ctx: bot.Context(session, error, dependencies),
  parameters parameters: types.ForwardMessageParameters,
) -> Result(types.Message, error.TelegaError)

Use this method to forward messages of any kind. Service messages and messages with protected content can’t be forwarded. On success, the sent Message is returned.

Official reference: https://core.telegram.org/bots/api#forwardmessage

with_dice

</>

pub fn with_dice(
  ctx ctx: bot.Context(session, error, dependencies),
  parameters parameters: option.Option(types.SendDiceParameters),
) -> Result(types.Message, error.TelegaError)

Use this method to send an animated emoji that will display a random value.

Official reference: https://core.telegram.org/bots/api#senddice

with_ephemeral

</>

pub fn with_ephemeral(
  ctx ctx: bot.Context(session, error, dependencies),
  text text: String,
  parameters ephemeral_message_parameters: types.EphemeralMessageParameters,
) -> Result(types.Message, error.TelegaError)

Use this method to send an ephemeral text message with explicit EphemeralMessageParameters (Bot API 10.3).

Official reference: https://core.telegram.org/bots/api#sendmessage

with_ephemeral_markup

</>

pub fn with_ephemeral_markup(
  ctx ctx: bot.Context(session, error, dependencies),
  text text: String,
  markup reply_markup: types.SendMessageReplyMarkupParameters,
) -> Result(types.Message, error.TelegaError)

Use this method to send an ephemeral text message with keyboard markup (Bot API 10.3).

Official reference: https://core.telegram.org/bots/api#sendmessage

with_ephemeral_text

</>

pub fn with_ephemeral_text(
  ctx ctx: bot.Context(session, error, dependencies),
  text text: String,
) -> Result(types.Message, error.TelegaError)

Use this method to send a text message that only one user of the chat sees (Bot API 10.3). Ephemeral messages work in group chats only; in private chats use with_text.

The message is aimed at the user of the current update — see ephemeral_parameters for finer control, and pass the result to with_ephemeral.

Official reference: https://core.telegram.org/bots/api#sendmessage

with_file_link

</>

pub fn with_file_link(
  ctx ctx: bot.Context(session, error, dependencies),
  file_id file_id: String,
) -> Result(String, error.TelegaError)

Get download link for the file.

with_formatted

</>

pub fn with_formatted(
  ctx ctx: bot.Context(session, error, dependencies),
  formatted formatted: format.FormattedText,
) -> Result(types.Message, error.TelegaError)

Use this method to send formatted text messages.

Example

let formatted = format.build()
  |> format.bold_text("Important!")
  |> format.to_formatted()
reply.with_formatted(ctx, formatted)

Official reference: https://core.telegram.org/bots/api#sendmessage

with_formatted_markup

</>

pub fn with_formatted_markup(
  ctx ctx: bot.Context(session, error, dependencies),
  formatted formatted: format.FormattedText,
  markup reply_markup: types.SendMessageReplyMarkupParameters,
) -> Result(types.Message, error.TelegaError)

Use this method to send formatted text messages with keyboard markup.

Official reference: https://core.telegram.org/bots/api#sendmessage

with_html

</>

pub fn with_html(
  ctx ctx: bot.Context(session, error, dependencies),
  html html: String,
) -> Result(types.Message, error.TelegaError)

Use this method to send HTML formatted text messages.

Example

let html = format.bold("Hello") <> " " <> format.italic("World")
reply.with_html(ctx, html)

Official reference: https://core.telegram.org/bots/api#sendmessage

with_invoice

</>

pub fn with_invoice(
  ctx ctx: bot.Context(session, error, dependencies),
  title title: String,
  description description: String,
  payload payload: String,
  currency currency: String,
  prices prices: List(#(String, Int)),
) -> Result(types.Message, error.TelegaError)

Use this method to send an invoice.

Official reference: https://core.telegram.org/bots/api#sendinvoice

with_markdown

</>

pub fn with_markdown(
  ctx ctx: bot.Context(session, error, dependencies),
  markdown markdown: String,
) -> Result(types.Message, error.TelegaError)

Use this method to send Markdown formatted text messages.

Example

reply.with_markdown(ctx, "*Bold* _Italic_")

Official reference: https://core.telegram.org/bots/api#sendmessage

with_markdown_v2

</>

pub fn with_markdown_v2(
  ctx ctx: bot.Context(session, error, dependencies),
  markdown markdown: String,
) -> Result(types.Message, error.TelegaError)

Use this method to send MarkdownV2 formatted text messages.

Example

reply.with_markdown_v2(ctx, "*Bold* _Italic_ __Underline__")

Official reference: https://core.telegram.org/bots/api#sendmessage

with_markup

</>

pub fn with_markup(
  ctx ctx: bot.Context(session, error, dependencies),
  text text: String,
  markup reply_markup: types.SendMessageReplyMarkupParameters,
) -> Result(types.Message, error.TelegaError)

Use this method to send text messages with keyboard markup.

Uses the client’s default parse mode if one is configured via client.set_default_parse_mode.

Official reference: https://core.telegram.org/bots/api#sendmessage

with_media_group

</>

pub fn with_media_group(
  ctx ctx: bot.Context(session, error, dependencies),
  media media: List(types.InputMedia),
) -> Result(List(types.Message), error.TelegaError)

Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio files can be only grouped in an album with messages of the same type. Returns a list of messages that were sent.

Example

let media_group = media_group.new()
  |> media_group.add_photo("https://example.com/photo1.jpg", None)
  |> media_group.add_photo("https://example.com/photo2.jpg", Some(
    media_group.PhotoOptions(
      caption: Some("Second photo"),
      parse_mode: Some("Markdown"),
      ..media_group.default_photo_options()
    )
  ))
  |> media_group.build()

reply.with_media_group(ctx, media_group)

Official reference: https://core.telegram.org/bots/api#sendmediagroup

with_paid_media

</>

pub fn with_paid_media(
  ctx ctx: bot.Context(session, error, dependencies),
  star_count star_count: Int,
  media media: List(types.InputPaidMedia),
) -> Result(types.Message, error.TelegaError)

Use this method to send paid media — photos and videos that the user must pay Telegram Stars to unlock.

Uses the client’s default parse mode if one is configured via client.set_default_parse_mode.

Example

reply.with_paid_media(ctx, star_count: 10, media: [
  types.InputPaidMediaPhotoInputPaidMedia(types.InputPaidMediaPhoto(
    type_: "photo",
    media: "https://example.com/photo.jpg",
  )),
])

Official reference: https://core.telegram.org/bots/api#sendpaidmedia

with_photo

</>

pub fn with_photo(
  ctx ctx: bot.Context(session, error, dependencies),
  photo photo: types.FileOrString,
  caption caption: option.Option(String),
) -> Result(types.Message, error.TelegaError)

Use this method to send a photo — by file_id, URL, or upload.

The caption uses the client’s default parse mode if one is configured via client.set_default_parse_mode.

Example

reply.with_photo(ctx, types.StringV("https://example.com/cat.jpg"), Some("A cat"))

Official reference: https://core.telegram.org/bots/api#sendphoto

with_photo_bytes

</>

pub fn with_photo_bytes(
  ctx ctx: bot.Context(session, error, dependencies),
  bytes bytes: BitArray,
  filename filename: String,
  content_type content_type: String,
  caption caption: option.Option(String),
) -> Result(types.Message, error.TelegaError)

Send a photo to the active chat by uploading raw bytes (multipart/form-data) — for art the bot holds in memory / object storage but has never sent before, so there is no file_id yet. The returned Message’s largest PhotoSize carries the new file_id; cache it and reuse with_photo (a plain JSON send) next time.

If caption is Some, the client’s default parse mode (if configured) is applied, matching with_photo.

with_poll

</>

pub fn with_poll(
  ctx ctx: bot.Context(session, error, dependencies),
  question question: String,
  options options: List(String),
) -> Result(types.Message, error.TelegaError)

Use this method to send a native poll.

Official reference: https://core.telegram.org/bots/api#sendpoll

with_sticker

</>

pub fn with_sticker(
  ctx ctx: bot.Context(session, error, dependencies),
  sticker sticker: types.FileOrString,
) -> Result(types.Message, error.TelegaError)

Use this method to send a sticker.

Official reference: https://core.telegram.org/bots/api#sendsticker

with_text

</>

pub fn with_text(
  ctx ctx: bot.Context(session, error, dependencies),
  text text: String,
) -> Result(types.Message, error.TelegaError)

Use this method to send text messages.

Uses the client’s default parse mode if one is configured via client.set_default_parse_mode.

Official reference: https://core.telegram.org/bots/api#sendmessage