Struct TelegramChannel 

pub struct TelegramChannel { /* private fields */ }

Telegram channel — long-polls the Bot API for updates

Implementations

impl TelegramChannel

pub fn new( bot_token: String, alias: impl Into<String>, peer_resolver: Arc<dyn Fn() -> Vec<String> + Send + Sync>, mention_only: bool, ) -> TelegramChannel

pub fn with_voice_peer_resolver( self, voice_peer_resolver: Arc<dyn Fn() -> Vec<String> + Send + Sync>, ) -> TelegramChannel

Set the resolver used to resolve voice-chat peers live (no cached state).

pub fn with_approval_timeout_secs(self, secs: u64) -> TelegramChannel

Override the approval prompt timeout (default 120s).

pub fn with_passive_group_context(self, enabled: bool) -> TelegramChannel

Record unaddressed group messages as passive context instead of dropping them.

pub fn with_ack_reactions(self, enabled: bool) -> TelegramChannel

Configure whether Telegram-native acknowledgement reactions are sent.

pub fn with_per_user_session(self, enabled: bool) -> TelegramChannel

Set by the orchestrator from [channels.telegram.<alias>].per_user_session. When false, group-chat messages carry ReplyTarget conversation scope, so every member of a group (or forum topic) shares one session keyed on the chat/topic. When true (default), group sessions stay sender-scoped. Direct messages are always sender-scoped either way.

pub fn with_proxy_url(self, proxy_url: Option<String>) -> TelegramChannel

Set a per-channel proxy URL that overrides the global proxy config.

pub fn with_tool_command_specs( self, specs: Vec<(String, String)>, ) -> TelegramChannel

Store pre-computed tool command specs for bot command registration.

pub fn with_workspace_dir(self, dir: PathBuf) -> TelegramChannel

Configure workspace directory for saving downloaded attachments.

pub fn with_streaming( self, stream_mode: StreamMode, draft_update_interval_ms: u64, ) -> TelegramChannel

Configure streaming mode for progressive draft updates or multi-message delivery.

pub fn with_api_base(self, api_base: String) -> TelegramChannel

Override the Telegram Bot API base URL. Useful for local Bot API servers or testing.

pub fn with_transcription(self, config: TranscriptionConfig) -> TelegramChannel

Configure voice transcription from a [transcription] snapshot.

Compatibility and test path. The daemon routes every channel through with_transcription_manager with a manager built from live config and the owning agent’s resolved provider; this path can only see the legacy section, so it binds a lone registered provider and otherwise leaves the choice unbound (see transcription::manager_from_snapshot).

pub fn with_tts(self, config: &Config) -> TelegramChannel

pub fn with_persistence_authority( self, authority: LiveConfigAuthority, ) -> TelegramChannel

Wire the daemon generation’s live-config authority for pairing writes.

pub async fn send_document( &self, chat_id: &str, thread_id: Option<&str>, file_path: &Path, caption: Option<&str>, ) -> Result<(), Error>

Send a document/file to a Telegram chat

pub async fn send_document_bytes( &self, chat_id: &str, thread_id: Option<&str>, file_bytes: Vec<u8>, file_name: &str, caption: Option<&str>, ) -> Result<(), Error>

Send a document from bytes (in-memory) to a Telegram chat

pub async fn send_photo( &self, chat_id: &str, thread_id: Option<&str>, file_path: &Path, caption: Option<&str>, ) -> Result<(), Error>

Send a photo to a Telegram chat

pub async fn send_photo_bytes( &self, chat_id: &str, thread_id: Option<&str>, file_bytes: Vec<u8>, file_name: &str, caption: Option<&str>, ) -> Result<(), Error>

Send a photo from bytes (in-memory) to a Telegram chat

pub async fn send_video( &self, chat_id: &str, thread_id: Option<&str>, file_path: &Path, caption: Option<&str>, ) -> Result<(), Error>

Send a video to a Telegram chat

pub async fn send_audio( &self, chat_id: &str, thread_id: Option<&str>, file_path: &Path, caption: Option<&str>, ) -> Result<(), Error>

Send an audio file to a Telegram chat

pub async fn send_voice( &self, chat_id: &str, thread_id: Option<&str>, file_path: &Path, caption: Option<&str>, ) -> Result<(), Error>

Send a voice message to a Telegram chat

pub async fn send_document_by_url( &self, chat_id: &str, thread_id: Option<&str>, url: &str, caption: Option<&str>, ) -> Result<(), Error>

Send a file by URL (Telegram will download it)

pub async fn send_photo_by_url( &self, chat_id: &str, thread_id: Option<&str>, url: &str, caption: Option<&str>, ) -> Result<(), Error>

Send a photo by URL (Telegram will download it)

pub async fn send_video_by_url( &self, chat_id: &str, thread_id: Option<&str>, url: &str, caption: Option<&str>, ) -> Result<(), Error>

Send a video by URL (Telegram will download it)

pub async fn send_audio_by_url( &self, chat_id: &str, thread_id: Option<&str>, url: &str, caption: Option<&str>, ) -> Result<(), Error>

Send an audio file by URL (Telegram will download it)

pub async fn send_voice_by_url( &self, chat_id: &str, thread_id: Option<&str>, url: &str, caption: Option<&str>, ) -> Result<(), Error>

Send a voice message by URL (Telegram will download it)

Trait Implementations

impl Attributable for TelegramChannel

fn role(&self) -> Role

fn alias(&self) -> &str

fn tool_provenance(&self) -> ToolProvenance

Classifies whether a tool implementation is first-party native code or an extension. The conservative default prevents a new wrapper from inheriting native presentation privileges accidentally.

impl Channel for TelegramChannel

fn self_addressed_mention(&self) -> Option<String>

Telegram users mention the bot as @bot_username in chat. The cached bot_username from getMe is already the bare form; prepend @ to match what arrives in inbound message text.

fn request_approval<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, recipient: &'life1 str, request: &'life2 ChannelApprovalRequest, ) -> Pin<Box<dyn Future<Output = Result<Option<ChannelApprovalResponse>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, TelegramChannel: 'async_trait,

Delegates to Self::request_approval_attributed and drops the provenance, so the prompt/timeout logic lives in exactly one place.

fn name(&self) -> &str

Human-readable channel name

fn self_handle(&self) -> Option<String>

Self-loop guard for multi-agent runs: the bot’s own handle/identity on this channel, so the orchestrator can drop inbound events whose sender matches. A bot must never respond to its own messages, even if a misconfigured peer group lists the bot’s handle as an external peer.

fn supports_draft_updates(&self) -> bool

Whether this channel supports progressive message updates via draft edits.

fn present_model_picker<'life0, 'life1, 'async_trait>( &'life0 self, request: &'life1 ChannelModelPickerRequest, ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, TelegramChannel: 'async_trait,

Present a channel-native model picker for a bare /model command.

fn supports_multi_message_streaming(&self) -> bool

Whether this channel supports multi-message streaming delivery.

fn supports_turn_flush_narration(&self) -> bool

Whether this channel implements the turn-flush narration contract: flush_draft_turn delivers each completed agent text turn as a permanent outbound message, and the orchestrator therefore routes that narration through the outbound hook + leak-detection boundary and orders it ahead of the approval prompt via a flush barrier.

fn multi_message_delay_ms(&self) -> u64

Minimum delay (ms) between successive messages in multi-message mode. The message boundary is channel-specific (for example, Telegram uses completed agent turns).

fn send_draft<'life0, 'life1, 'async_trait>( &'life0 self, message: &'life1 SendMessage, ) -> Pin<Box<dyn Future<Output = Result<Option<String>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, TelegramChannel: 'async_trait,

Send an initial draft message. Returns a platform-specific message ID for later edits.

fn update_draft<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, recipient: &'life1 str, message_id: &'life2 str, text: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, TelegramChannel: 'async_trait,

Update a previously sent draft message with new accumulated content.

fn flush_draft_turn<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, recipient: &'life1 str, message_id: &'life2 str, text: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, TelegramChannel: 'async_trait,

Flush the current agent text turn as an outbound message in multi-message streaming mode. Called when an LLM turn completes (e.g. before tool execution). Default: no-op.

fn discard_draft_turn<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, recipient: &'life1 str, message_id: &'life2 str, text: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, TelegramChannel: 'async_trait,

Discard a completed agent text turn WITHOUT sending it, marking that narration consumed for this draft. Called when the outbound hook cancels a narration flush: the cancelled turn must never be re-offered (no resurrection), but narration produced by a later turn must still be deliverable. Advancing the channel’s delivered-prefix bookkeeping over the cancelled text achieves both. Default: no-op.

fn update_draft_lifecycle<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, recipient: &'life1 str, message_id: &'life2 str, event: ProgressEvent, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, TelegramChannel: 'async_trait,

Show localized lifecycle progress produced from a typed runtime event. Unlike raw tool status text, this input is trusted channel chrome.

fn finalize_draft<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, recipient: &'life1 str, message_id: &'life2 str, text: &'life3 str, suppress_voice: bool, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, TelegramChannel: 'async_trait,

Finalize a draft with the complete response (e.g. apply Markdown formatting). suppress_voice forces text delivery even on voice-only peers.

fn cancel_draft<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, recipient: &'life1 str, message_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, TelegramChannel: 'async_trait,

Cancel and remove a previously sent draft message if the channel supports it.

fn send<'life0, 'life1, 'async_trait>( &'life0 self, message: &'life1 SendMessage, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, TelegramChannel: 'async_trait,

Send a message through this channel

fn listen<'life0, 'async_trait>( &'life0 self, tx: Sender<ChannelMessage>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, TelegramChannel: 'async_trait,

Start listening for incoming messages (long-running)

fn listener_health(&self) -> Option<ListenerHealth>

Listener health as the channel itself last observed it.

fn health_check<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where 'life0: 'async_trait, TelegramChannel: 'async_trait,

Check if channel is healthy

fn start_typing<'life0, 'life1, 'async_trait>( &'life0 self, recipient: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, TelegramChannel: 'async_trait,

Signal that the bot is processing a response (e.g. “typing” indicator).

fn stop_typing<'life0, 'life1, 'async_trait>( &'life0 self, _recipient: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, TelegramChannel: 'async_trait,

Stop any active typing indicator.

fn request_approval_attributed<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, recipient: &'life1 str, request: &'life2 ChannelApprovalRequest, ) -> Pin<Box<dyn Future<Output = Result<Option<AttributedApprovalResponse>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, TelegramChannel: 'async_trait,

Like Channel::request_approval, but also reports WHO produced the decision: which back-channel answered (decided_by) and whether a person answered at all (ApprovalSource).

fn request_approval_attributed_with_timeout<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, recipient: &'life1 str, request: &'life2 ChannelApprovalRequest, timeout: Duration, ) -> Pin<Box<dyn Future<Output = Result<Option<AttributedApprovalResponse>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, TelegramChannel: 'async_trait,

Request an attributed approval using a caller-owned response budget.

fn send_final<'life0, 'life1, 'async_trait>( &'life0 self, message: &'life1 SendMessage, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Send the completed assistant response for a turn.

fn set_cancel_token(&self, _token: CancellationToken)

Receive the supervisor lifecycle token before listen() is called. Channels that internally wait for shutdown can subscribe instead of independently catching SIGINT.

fn uses_cancel_token(&self) -> bool

Whether this channel participates in the cooperative cancellation contract via set_cancel_token. Only participating channels get a bounded grace period for cleanup after cancellation.

fn send_choice<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, recipient: &'life1 str, prompt: &'life2 str, options: &'life3 [(String, String)], ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: 'async_trait,

Send a discrete-choice prompt with options.

fn supports_native_polls(&self) -> bool

Whether this channel can post a native poll through Channel::send_poll. Callers check this before offering one, so a channel without native polls keeps whatever fallback the caller already had.

fn supports_outbound_send(&self) -> bool

Whether send actually delivers a message OUTBOUND on this channel. Default true. An INBOUND-ONLY transport (e.g. an AMQP trigger source whose send is a deliberate no-op that returns Ok) overrides this to false, so a surface that must genuinely deliver - such as the SOP approval route adapter - can refuse to route to it (and report the misconfiguration) instead of silently succeeding without sending anything.

fn drop_self_messages(&self, msg: &ChannelMessage) -> bool

Whether the orchestrator should drop an inbound message as self-authored (multi-agent self-loop guard). Default compares msg.sender against Self::self_handle case-insensitively after stripping a leading @ from each side. Override only for platforms whose identity comparison is non-string.

fn forge_request<'life0, 'async_trait>( &'life0 self, _request: ForgeApiRequest, ) -> Pin<Box<dyn Future<Output = Result<ForgeApiResponse, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

fn is_direct_message(&self, _msg: &ChannelMessage) -> bool

Whether an inbound message is a direct one-to-one conversation with the bot. A DM is definitionally addressed to the bot, so the orchestrator skips the reply-intent classifier and goes straight to the tool-capable agent turn. Default false: channels that cannot prove a one-to-one context keep the classifier precheck.

fn multi_message_confirmed_offset<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _recipient: &'life1 str, _message_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = usize> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Confirmed-delivery byte offset for a MultiMessage draft: how many bytes of the cumulative visible text previously handed to update_draft have already been emitted on the transport as paragraph messages (including their trailing \n\n delimiters).

fn update_draft_progress<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _recipient: &'life1 str, _message_id: &'life2 str, _text: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: 'async_trait,

Show a progress/status update (e.g. tool execution status).

fn update_draft_progress_batch<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, recipient: &'life1 str, message_id: &'life2 str, texts: &'life3 [String], ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: 'async_trait,

Show a batch of progress/status updates as one coalesced draft update.

fn update_typed_draft_progress_batch<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, recipient: &'life1 str, message_id: &'life2 str, progress: &'life3 [DraftProgress], ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: 'async_trait,

Show a batch of progress updates without discarding their source kind.

fn add_reaction<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, _emoji: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: 'async_trait,

Add a reaction (emoji) to a message.

fn remove_reaction<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, _emoji: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: 'async_trait,

Remove a reaction (emoji) from a message previously added by this bot.

fn pin_message<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Pin a message in the channel.

fn unpin_message<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Unpin a previously pinned message.

fn redact_message<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _channel_id: &'life1 str, _message_id: &'life2 str, _reason: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Redact (delete) a message from the channel.

fn create_room<'life0, 'life1, 'async_trait>( &'life0 self, _options: &'life1 RoomCreationOptions, ) -> Pin<Box<dyn Future<Output = Result<String, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Create a new platform room/conversation when the channel supports it.

fn send_poll<'life0, 'life1, 'async_trait>( &'life0 self, _poll: &'life1 PollRequest, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Post a native poll when the channel supports it.

fn invite_user<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _room_id: &'life1 str, _user_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Invite a user to an existing platform room/conversation.

fn room_context(&self, _room_id: &str) -> Option<ChannelRoomContext>

Context this channel supplies about room_id, when the adapter can provide it and the operator has opted the alias in.

fn send_gate_prompt<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _recipient: &'life1 str, _prompt: &'life2 ChannelGatePrompt, ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Present a long-lived, out-of-band gate prompt (e.g. a parked SOP approval) on this channel, rendered natively — an embed with one button per choice on Discord, an inline keyboard on Telegram, and so on.

fn finalize_gate_prompt<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _reference: &'life1 str, _outcome: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Mark a previously sent gate prompt as resolved: strip its interactive controls and replace the body with outcome (e.g. “Approved by @user — run resumed”), so a decided gate cannot be clicked again and the decision is visible in place. reference is the same correlation key the prompt was sent with. Best-effort: Ok(false) when this channel has nothing to finalize (no native prompt, or the mapping was lost to a restart) — the gate state itself is never affected.

fn request_choice<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _question: &'life1 str, _choices: &'life2 [String], _timeout: Duration, ) -> Pin<Box<dyn Future<Output = Result<Option<String>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Ask the user a multiple-choice question and return the chosen option’s text.

fn request_multi_choice<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _question: &'life1 str, _choices: &'life2 [String], _min_items: usize, _max_items: usize, _timeout: Duration, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<String>>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

fn supports_free_form_ask(&self) -> bool

Whether this channel can answer free-form (no-choices) ask_user questions via the standard send + listen flow. Channels that only handle structured choices return false so callers fail fast with a useful error instead of timing out on listen.