78b11b0319 2026-08-01 1: //! Telegram API integration for sending messages and attachments.
78b11b0319 2026-08-01 2:
f5ed284f8c 2025-06-21 3: use crate::utils::{
f5ed284f8c 2025-06-21 4: Attachment,
d87e80b9be 2026-01-12 5: validate,
f5ed284f8c 2025-06-21 6: };
f5ed284f8c 2025-06-21 7:
f5ed284f8c 2025-06-21 8: use std::{
f5ed284f8c 2025-06-21 9: collections::HashMap,
f5ed284f8c 2025-06-21 10: fmt::Debug,
f5ed284f8c 2025-06-21 11: };
f5ed284f8c 2025-06-21 12:
a044f68fa7 2025-08-23 13: use stacked_errors::{
78b11b0319 2026-08-01 14: bail,
f5ed284f8c 2025-06-21 15: Result,
a044f68fa7 2025-08-23 16: StackableErr,
f5ed284f8c 2025-06-21 17: };
f5ed284f8c 2025-06-21 18: use tgbot::{
f5ed284f8c 2025-06-21 19: api::Client,
f5ed284f8c 2025-06-21 20: types::{
f5ed284f8c 2025-06-21 21: ChatPeerId,
f5ed284f8c 2025-06-21 22: InputFile,
f5ed284f8c 2025-06-21 23: InputFileReader,
f5ed284f8c 2025-06-21 24: InputMediaDocument,
f5ed284f8c 2025-06-21 25: MediaGroup,
f5ed284f8c 2025-06-21 26: MediaGroupItem,
f5ed284f8c 2025-06-21 27: Message,
d87e80b9be 2026-01-12 28: ParseMode::Html,
f5ed284f8c 2025-06-21 29: SendMediaGroup,
f5ed284f8c 2025-06-21 30: SendMessage,
f5ed284f8c 2025-06-21 31: SendDocument,
f5ed284f8c 2025-06-21 32: },
f5ed284f8c 2025-06-21 33: };
f5ed284f8c 2025-06-21 34:
f5ed284f8c 2025-06-21 35: #[derive(Debug)]
f5ed284f8c 2025-06-21 36: pub struct TelegramTransport {
f5ed284f8c 2025-06-21 37: tg: Client,
f5ed284f8c 2025-06-21 38: recipients: HashMap<String, ChatPeerId>,
f5ed284f8c 2025-06-21 39: pub default: ChatPeerId,
f5ed284f8c 2025-06-21 40: }
f5ed284f8c 2025-06-21 41:
f5ed284f8c 2025-06-21 42: impl TelegramTransport {
78b11b0319 2026-08-01 43: /// Creates a new `TelegramTransport` instance.
78b11b0319 2026-08-01 44: ///
78b11b0319 2026-08-01 45: /// # Arguments
78b11b0319 2026-08-01 46: /// * `api_key` - Telegram Bot API token.
78b11b0319 2026-08-01 47: /// * `recipients` - Mapping of email addresses to Telegram chat IDs.
78b11b0319 2026-08-01 48: /// * `settings` - Additional configuration (API gateway, default chat).
78b11b0319 2026-08-01 49: ///
78b11b0319 2026-08-01 50: /// # Errors
78b11b0319 2026-08-01 51: /// Returns an error if configuration values cannot be read or if Telegram
78b11b0319 2026-08-01 52: /// API client creation fails.
14ef340959 2026-01-01 53: pub fn new (api_key: String, recipients: HashMap<String, i64>, settings: &config::Config) -> Result<TelegramTransport> {
14ef340959 2026-01-01 54: let default = settings.get_int("default")
14ef340959 2026-01-01 55: .context("[smtp2tg.toml] missing \"default\" recipient.\n")?;
14ef340959 2026-01-01 56: let api_gateway = settings.get_string("api_gateway")
14ef340959 2026-01-01 57: .context("[smtp2tg.toml] missing \"api_gateway\" destination.\n")?;
d87e80b9be 2026-01-12 58:
f5ed284f8c 2025-06-21 59: let tg = Client::new(api_key)
14ef340959 2026-01-01 60: .context("Failed to create API.\n")?
14ef340959 2026-01-01 61: .with_host(api_gateway);
f5ed284f8c 2025-06-21 62: let recipients = recipients.into_iter()
f5ed284f8c 2025-06-21 63: .map(|(a, b)| (a, ChatPeerId::from(b))).collect();
f5ed284f8c 2025-06-21 64: let default = ChatPeerId::from(default);
f5ed284f8c 2025-06-21 65:
f5ed284f8c 2025-06-21 66: Ok(TelegramTransport {
f5ed284f8c 2025-06-21 67: tg,
f5ed284f8c 2025-06-21 68: recipients,
f5ed284f8c 2025-06-21 69: default,
f5ed284f8c 2025-06-21 70: })
f5ed284f8c 2025-06-21 71: }
f5ed284f8c 2025-06-21 72:
78b11b0319 2026-08-01 73: /// Sends a debug message to the default chat.
78b11b0319 2026-08-01 74: ///
78b11b0319 2026-08-01 75: /// # Arguments
78b11b0319 2026-08-01 76: /// * `msg` - Message text to send.
78b11b0319 2026-08-01 77: ///
78b11b0319 2026-08-01 78: /// # Returns
78b11b0319 2026-08-01 79: /// * `Result<Message>` - Telegram API response.
78b11b0319 2026-08-01 80: ///
78b11b0319 2026-08-01 81: /// # Errors
78b11b0319 2026-08-01 82: /// Returns an error if `msg` contains a closing Telegram tag or sending fails.
f5ed284f8c 2025-06-21 83: pub async fn debug (&self, msg: &str) -> Result<Message> {
d87e80b9be 2026-01-12 84: self.send(&self.default, format!("<pre>{}</pre>", validate(msg).stack()?)).await
f5ed284f8c 2025-06-21 85: }
f5ed284f8c 2025-06-21 86:
78b11b0319 2026-08-01 87: /// Retrieves a chat ID by name.
78b11b0319 2026-08-01 88: ///
78b11b0319 2026-08-01 89: /// # Arguments
78b11b0319 2026-08-01 90: /// * `name` - Name or email to look up.
78b11b0319 2026-08-01 91: ///
78b11b0319 2026-08-01 92: /// # Returns
78b11b0319 2026-08-01 93: /// * `Result<&ChatPeerId>` - Chat ID if found.
78b11b0319 2026-08-01 94: ///
78b11b0319 2026-08-01 95: /// # Errors
78b11b0319 2026-08-01 96: /// Returns an error if `name` is not configured.
f5ed284f8c 2025-06-21 97: pub fn get (&self, name: &str) -> Result<&ChatPeerId> {
78b11b0319 2026-08-01 98: self.recipients.get(&name.to_lowercase())
f5ed284f8c 2025-06-21 99: .with_context(|| format!("Recipient \"{name}\" not found in configuration"))
f5ed284f8c 2025-06-21 100: }
f5ed284f8c 2025-06-21 101:
78b11b0319 2026-08-01 102: /// Sends a text message to a specified chat.
78b11b0319 2026-08-01 103: ///
78b11b0319 2026-08-01 104: /// # Arguments
78b11b0319 2026-08-01 105: /// * `to` - Target chat ID.
78b11b0319 2026-08-01 106: /// * `msg` - Message text (supports HTML formatting).
78b11b0319 2026-08-01 107: ///
78b11b0319 2026-08-01 108: /// # Returns
78b11b0319 2026-08-01 109: /// * `Result<Message>` - Telegram API response.
f5ed284f8c 2025-06-21 110: pub async fn send <S> (&self, to: &ChatPeerId, msg: S) -> Result<Message>
f5ed284f8c 2025-06-21 111: where S: Into<String> + Debug{
a044f68fa7 2025-08-23 112: self.tg.execute(
f5ed284f8c 2025-06-21 113: SendMessage::new(*to, msg)
d87e80b9be 2026-01-12 114: .with_parse_mode(Html)
a044f68fa7 2025-08-23 115: ).await.stack()
f5ed284f8c 2025-06-21 116: }
f5ed284f8c 2025-06-21 117:
78b11b0319 2026-08-01 118: /// Sends a message with attachments to a specified chat.
78b11b0319 2026-08-01 119: ///
78b11b0319 2026-08-01 120: /// # Arguments
78b11b0319 2026-08-01 121: /// * `to` - Target chat ID.
78b11b0319 2026-08-01 122: /// * `media` - List of attachments, non-empty.
78b11b0319 2026-08-01 123: /// * `msg` - Message text (supports HTML formatting).
78b11b0319 2026-08-01 124: ///
78b11b0319 2026-08-01 125: /// # Returns
78b11b0319 2026-08-01 126: /// * `Result<()>` - Success or error.
f5ed284f8c 2025-06-21 127: pub async fn sendgroup (&self, to: &ChatPeerId, media: Vec<Attachment>, msg: &str) -> Result<()> {
f5ed284f8c 2025-06-21 128: if media.len() > 1 {
f5ed284f8c 2025-06-21 129: let mut attach = vec![];
f5ed284f8c 2025-06-21 130: let mut pos = media.len();
f5ed284f8c 2025-06-21 131: for file in media {
f5ed284f8c 2025-06-21 132: let mut caption = InputMediaDocument::default();
f5ed284f8c 2025-06-21 133: if pos == 1 {
f5ed284f8c 2025-06-21 134: caption = caption.with_caption(msg)
d87e80b9be 2026-01-12 135: .with_caption_parse_mode(Html);
f5ed284f8c 2025-06-21 136: }
f5ed284f8c 2025-06-21 137: pos -= 1;
f5ed284f8c 2025-06-21 138: attach.push(
f5ed284f8c 2025-06-21 139: MediaGroupItem::for_document(
f5ed284f8c 2025-06-21 140: InputFile::from(
f5ed284f8c 2025-06-21 141: InputFileReader::from(file.data)
f5ed284f8c 2025-06-21 142: .with_file_name(file.name)
f5ed284f8c 2025-06-21 143: ),
f5ed284f8c 2025-06-21 144: caption
f5ed284f8c 2025-06-21 145: )
f5ed284f8c 2025-06-21 146: );
f5ed284f8c 2025-06-21 147: }
a044f68fa7 2025-08-23 148: self.tg.execute(SendMediaGroup::new(*to, MediaGroup::new(attach).stack()?)).await.stack()?;
f5ed284f8c 2025-06-21 149: } else {
78b11b0319 2026-08-01 150: if media.is_empty() {
78b11b0319 2026-08-01 151: bail!("At least one attachment is required.");
78b11b0319 2026-08-01 152: }
f5ed284f8c 2025-06-21 153: self.tg.execute(
f5ed284f8c 2025-06-21 154: SendDocument::new(
f5ed284f8c 2025-06-21 155: *to,
f5ed284f8c 2025-06-21 156: InputFileReader::from(media[0].data.clone())
f5ed284f8c 2025-06-21 157: .with_file_name(media[0].name.clone())
f5ed284f8c 2025-06-21 158: ).with_caption(msg)
d87e80b9be 2026-01-12 159: .with_caption_parse_mode(Html)
a044f68fa7 2025-08-23 160: ).await.stack()?;
f5ed284f8c 2025-06-21 161: }
f5ed284f8c 2025-06-21 162: Ok(())
f5ed284f8c 2025-06-21 163: }
f5ed284f8c 2025-06-21 164: }