512369f93e 2026-08-01 arcade: //! Telegram API integration for sending messages and attachments.
512369f93e 2026-08-01 arcade:
c996f5c871 2026-01-12 arcade: use crate::utils::{
c996f5c871 2026-01-12 arcade: Attachment,
c996f5c871 2026-01-12 arcade: validate,
c996f5c871 2026-01-12 arcade: };
f5ed284f8c 2025-06-21 arcade:
f5ed284f8c 2025-06-21 arcade: use std::{
f5ed284f8c 2025-06-21 arcade: collections::HashMap,
f5ed284f8c 2025-06-21 arcade: fmt::Debug,
f5ed284f8c 2025-06-21 arcade: };
f5ed284f8c 2025-06-21 arcade:
a044f68fa7 2025-08-23 arcade: use stacked_errors::{
1723b63d69 2026-08-01 arcade: bail,
f5ed284f8c 2025-06-21 arcade: Result,
a044f68fa7 2025-08-23 arcade: StackableErr,
f5ed284f8c 2025-06-21 arcade: };
f5ed284f8c 2025-06-21 arcade: use tgbot::{
f5ed284f8c 2025-06-21 arcade: api::Client,
f5ed284f8c 2025-06-21 arcade: types::{
f5ed284f8c 2025-06-21 arcade: ChatPeerId,
f5ed284f8c 2025-06-21 arcade: InputFile,
f5ed284f8c 2025-06-21 arcade: InputFileReader,
f5ed284f8c 2025-06-21 arcade: InputMediaDocument,
f5ed284f8c 2025-06-21 arcade: MediaGroup,
f5ed284f8c 2025-06-21 arcade: MediaGroupItem,
f5ed284f8c 2025-06-21 arcade: Message,
0f47e23e21 2026-01-12 arcade: ParseMode::Html,
f5ed284f8c 2025-06-21 arcade: SendMediaGroup,
f5ed284f8c 2025-06-21 arcade: SendMessage,
f5ed284f8c 2025-06-21 arcade: SendDocument,
f5ed284f8c 2025-06-21 arcade: },
f5ed284f8c 2025-06-21 arcade: };
f5ed284f8c 2025-06-21 arcade:
f5ed284f8c 2025-06-21 arcade: #[derive(Debug)]
f5ed284f8c 2025-06-21 arcade: pub struct TelegramTransport {
f5ed284f8c 2025-06-21 arcade: tg: Client,
f5ed284f8c 2025-06-21 arcade: recipients: HashMap<String, ChatPeerId>,
f5ed284f8c 2025-06-21 arcade: pub default: ChatPeerId,
f5ed284f8c 2025-06-21 arcade: }
f5ed284f8c 2025-06-21 arcade:
f5ed284f8c 2025-06-21 arcade: impl TelegramTransport {
512369f93e 2026-08-01 arcade: /// Creates a new `TelegramTransport` instance.
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Arguments
512369f93e 2026-08-01 arcade: /// * `api_key` - Telegram Bot API token.
512369f93e 2026-08-01 arcade: /// * `recipients` - Mapping of email addresses to Telegram chat IDs.
512369f93e 2026-08-01 arcade: /// * `settings` - Additional configuration (API gateway, default chat).
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Errors
1723b63d69 2026-08-01 arcade: /// Returns an error if configuration values cannot be read or if Telegram
1723b63d69 2026-08-01 arcade: /// API client creation fails.
14ef340959 2026-01-01 arcade: pub fn new (api_key: String, recipients: HashMap<String, i64>, settings: &config::Config) -> Result<TelegramTransport> {
14ef340959 2026-01-01 arcade: let default = settings.get_int("default")
14ef340959 2026-01-01 arcade: .context("[smtp2tg.toml] missing \"default\" recipient.\n")?;
14ef340959 2026-01-01 arcade: let api_gateway = settings.get_string("api_gateway")
14ef340959 2026-01-01 arcade: .context("[smtp2tg.toml] missing \"api_gateway\" destination.\n")?;
0f47e23e21 2026-01-12 arcade:
f5ed284f8c 2025-06-21 arcade: let tg = Client::new(api_key)
14ef340959 2026-01-01 arcade: .context("Failed to create API.\n")?
14ef340959 2026-01-01 arcade: .with_host(api_gateway);
f5ed284f8c 2025-06-21 arcade: let recipients = recipients.into_iter()
f5ed284f8c 2025-06-21 arcade: .map(|(a, b)| (a, ChatPeerId::from(b))).collect();
f5ed284f8c 2025-06-21 arcade: let default = ChatPeerId::from(default);
f5ed284f8c 2025-06-21 arcade:
f5ed284f8c 2025-06-21 arcade: Ok(TelegramTransport {
f5ed284f8c 2025-06-21 arcade: tg,
f5ed284f8c 2025-06-21 arcade: recipients,
f5ed284f8c 2025-06-21 arcade: default,
f5ed284f8c 2025-06-21 arcade: })
f5ed284f8c 2025-06-21 arcade: }
f5ed284f8c 2025-06-21 arcade:
512369f93e 2026-08-01 arcade: /// Sends a debug message to the default chat.
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Arguments
512369f93e 2026-08-01 arcade: /// * `msg` - Message text to send.
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Returns
512369f93e 2026-08-01 arcade: /// * `Result<Message>` - Telegram API response.
1723b63d69 2026-08-01 arcade: ///
1723b63d69 2026-08-01 arcade: /// # Errors
1723b63d69 2026-08-01 arcade: /// Returns an error if `msg` contains a closing Telegram tag or sending fails.
f5ed284f8c 2025-06-21 arcade: pub async fn debug (&self, msg: &str) -> Result<Message> {
c996f5c871 2026-01-12 arcade: self.send(&self.default, format!("<pre>{}</pre>", validate(msg).stack()?)).await
f5ed284f8c 2025-06-21 arcade: }
f5ed284f8c 2025-06-21 arcade:
512369f93e 2026-08-01 arcade: /// Retrieves a chat ID by name.
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Arguments
512369f93e 2026-08-01 arcade: /// * `name` - Name or email to look up.
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Returns
512369f93e 2026-08-01 arcade: /// * `Result<&ChatPeerId>` - Chat ID if found.
1723b63d69 2026-08-01 arcade: ///
1723b63d69 2026-08-01 arcade: /// # Errors
1723b63d69 2026-08-01 arcade: /// Returns an error if `name` is not configured.
f5ed284f8c 2025-06-21 arcade: pub fn get (&self, name: &str) -> Result<&ChatPeerId> {
aaa78fed23 2026-08-01 arcade: self.recipients.get(&name.to_lowercase())
f5ed284f8c 2025-06-21 arcade: .with_context(|| format!("Recipient \"{name}\" not found in configuration"))
f5ed284f8c 2025-06-21 arcade: }
f5ed284f8c 2025-06-21 arcade:
512369f93e 2026-08-01 arcade: /// Sends a text message to a specified chat.
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Arguments
512369f93e 2026-08-01 arcade: /// * `to` - Target chat ID.
512369f93e 2026-08-01 arcade: /// * `msg` - Message text (supports HTML formatting).
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Returns
512369f93e 2026-08-01 arcade: /// * `Result<Message>` - Telegram API response.
f5ed284f8c 2025-06-21 arcade: pub async fn send <S> (&self, to: &ChatPeerId, msg: S) -> Result<Message>
f5ed284f8c 2025-06-21 arcade: where S: Into<String> + Debug{
a044f68fa7 2025-08-23 arcade: self.tg.execute(
f5ed284f8c 2025-06-21 arcade: SendMessage::new(*to, msg)
0f47e23e21 2026-01-12 arcade: .with_parse_mode(Html)
a044f68fa7 2025-08-23 arcade: ).await.stack()
f5ed284f8c 2025-06-21 arcade: }
f5ed284f8c 2025-06-21 arcade:
512369f93e 2026-08-01 arcade: /// Sends a message with attachments to a specified chat.
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Arguments
512369f93e 2026-08-01 arcade: /// * `to` - Target chat ID.
1723b63d69 2026-08-01 arcade: /// * `media` - List of attachments, non-empty.
512369f93e 2026-08-01 arcade: /// * `msg` - Message text (supports HTML formatting).
512369f93e 2026-08-01 arcade: ///
512369f93e 2026-08-01 arcade: /// # Returns
512369f93e 2026-08-01 arcade: /// * `Result<()>` - Success or error.
f5ed284f8c 2025-06-21 arcade: pub async fn sendgroup (&self, to: &ChatPeerId, media: Vec<Attachment>, msg: &str) -> Result<()> {
f5ed284f8c 2025-06-21 arcade: if media.len() > 1 {
f5ed284f8c 2025-06-21 arcade: let mut attach = vec![];
f5ed284f8c 2025-06-21 arcade: let mut pos = media.len();
f5ed284f8c 2025-06-21 arcade: for file in media {
f5ed284f8c 2025-06-21 arcade: let mut caption = InputMediaDocument::default();
f5ed284f8c 2025-06-21 arcade: if pos == 1 {
f5ed284f8c 2025-06-21 arcade: caption = caption.with_caption(msg)
0f47e23e21 2026-01-12 arcade: .with_caption_parse_mode(Html);
f5ed284f8c 2025-06-21 arcade: }
f5ed284f8c 2025-06-21 arcade: pos -= 1;
f5ed284f8c 2025-06-21 arcade: attach.push(
f5ed284f8c 2025-06-21 arcade: MediaGroupItem::for_document(
f5ed284f8c 2025-06-21 arcade: InputFile::from(
f5ed284f8c 2025-06-21 arcade: InputFileReader::from(file.data)
f5ed284f8c 2025-06-21 arcade: .with_file_name(file.name)
f5ed284f8c 2025-06-21 arcade: ),
f5ed284f8c 2025-06-21 arcade: caption
f5ed284f8c 2025-06-21 arcade: )
f5ed284f8c 2025-06-21 arcade: );
f5ed284f8c 2025-06-21 arcade: }
a044f68fa7 2025-08-23 arcade: self.tg.execute(SendMediaGroup::new(*to, MediaGroup::new(attach).stack()?)).await.stack()?;
f5ed284f8c 2025-06-21 arcade: } else {
1723b63d69 2026-08-01 arcade: if media.is_empty() {
1723b63d69 2026-08-01 arcade: bail!("At least one attachment is required.");
1723b63d69 2026-08-01 arcade: }
f5ed284f8c 2025-06-21 arcade: self.tg.execute(
f5ed284f8c 2025-06-21 arcade: SendDocument::new(
f5ed284f8c 2025-06-21 arcade: *to,
f5ed284f8c 2025-06-21 arcade: InputFileReader::from(media[0].data.clone())
f5ed284f8c 2025-06-21 arcade: .with_file_name(media[0].name.clone())
f5ed284f8c 2025-06-21 arcade: ).with_caption(msg)
0f47e23e21 2026-01-12 arcade: .with_caption_parse_mode(Html)
a044f68fa7 2025-08-23 arcade: ).await.stack()?;
f5ed284f8c 2025-06-21 arcade: }
f5ed284f8c 2025-06-21 arcade: Ok(())
f5ed284f8c 2025-06-21 arcade: }
f5ed284f8c 2025-06-21 arcade: }