Bifrost — Telegram Bridge

Bifrost is Yukkai's remote communication bridge. It connects your Telegram account to Yukkai's ConversationEngine, allowing you to send commands and receive responses directly through Telegram — whether you're across the room or across the globe.

What Bifrost Does

Bifrost translates Telegram messages into Yukkai commands and vice versa. This means you can:

• Send text messages — Ask Yukkai questions, give instructions, or have a conversation
• Receive photos — Get generated images, screenshots, or file previews delivered to your phone
• Receive documents — Get PDFs, code files, archives, or any file Yukkai produces
• Receive audio — Get audio files or voice messages
• Receive videos — Get generated or processed video clips
• Check connection status — Verify that the bridge is active and see connected chats

How It Works

Telegram → BifrostBridge → ConversationEngine → Response → BifrostBridge → Telegram

1. You send a message to your Yukkai Telegram bot
2. BifrostBridge receives it and forwards it to the ConversationEngine
3. The ConversationEngine processes the message (LLM call, tool execution, etc.)
4. The response is sent back through BifrostBridge to your Telegram chat
5. Media (images, documents, audio, video) is delivered as Telegram attachments

Sending Messages and Media

Yukkai uses the bifrost_send tool to deliver content to Telegram. Here's how each type works:

Text Messages

bifrost_send(action: "send_text", chat_id: "12345", text: "Your task is complete!")

Photos

bifrost_send(action: "send_photo", chat_id: "12345",
  file_path: "~/YukkaiDocs/sunset.png",
  caption: "Here's the sunset image you asked for")

Documents

bifrost_send(action: "send_document", chat_id: "12345",
  file_path: "~/Documents/report.pdf",
  caption: "Q3 report, as requested")

Audio

bifrost_send(action: "send_audio", chat_id: "12345",
  file_path: "~/YukkaiDocs/track.mp3",
  caption: "Generated music clip")

Video

bifrost_send(action: "send_video", chat_id: "12345",
  file_path: "~/YukkaiDocs/clip.mp4",
  caption: "Generated video clip")

Voice Messages

bifrost_send(action: "send_voice", chat_id: "12345",
  file_path: "~/YukkaiDocs/voice.caf")

Checking Connection Status

Before sending time-sensitive messages, check that the bridge is active:

bifrost_send(action: "status")

This returns the state of connected transports and active chats. If you don't know the target chat_id, check status first — it lists authorized chats.

Security

Bifrost inherits Yukkai's multi-layer security:

• Only authorized users can send and receive through the bot. Authorization is enforced server-side.
• All security gates apply — SecretDetector, InjectionDetector, LLMController, and PathGuard all process incoming Telegram messages just like local ones.
• No additional authentication is needed on the client side — if you're authorized, you're in.

Best Practices

✅ Do

• Always include captions on documents sent out of context — the recipient should know what they're receiving and why.
• Use send_document for non-media files — PDFs, code files, zip archives should go as documents, not photos.
• Check status first for time-sensitive deliveries to confirm the connection is active.
• Use send_photo for images — Telegram renders these inline, making them immediately viewable.

❌ Don't

• Don't send large batches of files in rapid succession without checking delivery — verify the connection is active first.
• Don't use send_photo for non-image files — it will fail or render incorrectly. Use send_document instead.
• Don't omit captions on unexpected documents — the recipient may not understand the context.

Common Use Cases

• Remote task monitoring — Start a long-running task on your Mac, receive a Telegram notification when it's done
• Deliver generated content — Get AI-generated images, music, or videos sent directly to your phone
• Ask questions on the go — Send a quick question to Yukkai from Telegram and get a response without opening your Mac
• Share reports — Have Yukkai generate and deliver a report as a PDF document to your Telegram