docs: add Remote Access section with Telegram Gateway documentation (#7955)

Signed-off-by: Rizel Scarlett <rizel@squareup.com>
2026-03-17 15:40:17 -04:00
parent 5cc7411c9a
commit d2dbffa497
7 changed files with 219 additions and 77 deletions
@@ -0,0 +1,106 @@
+---
+title: Telegram Gateway
+sidebar_position: 2
+sidebar_label: Telegram Gateway
+description: Chat with goose through Telegram from any device.
+---
+
+The Telegram Gateway lets you interact with goose through Telegram, enabling remote access from any device where Telegram is available.
+
+:::warning Experimental Feature
+The Gateway feature is experimental and in active development. Behavior and configuration may change in future releases.
+:::
+
+## How It Works
+
+The Gateway connects your Telegram account to goose through a secure pairing process. Once paired, you can send messages to a Telegram bot that forwards them to goose, and receive formatted responses back in Telegram.
+
+**Key details:**
+- Uses a Telegram bot that you create and configure
+- Secure pairing with a one-time code
+- Supports formatted responses with code blocks and markdown
+- Maintains a persistent session that auto-compacts for long conversations
+- Works from any device with Telegram installed
+
+## Prerequisites
+
+Before setting up the Telegram Gateway, you need to create a Telegram bot:
+
+1. Open Telegram and search for [@BotFather](https://t.me/BotFather)
+2. Send `/newbot` and follow the prompts to create your bot
+3. Copy the **bot token** that BotFather provides (looks like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)
+
+:::tip
+Keep your bot token secure. Anyone with the token can control your bot.
+:::
+
+## Setup
+
+### Desktop App
+
+1. Open goose Desktop
+2. Go to **Settings** > **Gateways**
+3. In the Telegram section, enter your bot token
+4. Click **Start** to activate the gateway
+5. Click **Generate Pairing Code** to get a one-time pairing code
+
+### Pair Your Telegram Account
+
+1. Open Telegram and find your bot (search for the username you gave it)
+2. Send the pairing code to the bot
+3. The bot will confirm the pairing is complete
+
+You can now chat with goose through Telegram!
+
+### CLI Usage
+
+You can also manage the gateway from the command line:
+
+```bash
+# Check gateway status
+goose gateway status
+
+# Start the Telegram gateway
+goose gateway start telegram --bot-token YOUR_BOT_TOKEN
+
+# Generate a pairing code
+goose gateway pair telegram
+
+# Stop the gateway
+goose gateway stop telegram
+```
+
+## What You Can Do
+
+Once paired, you can:
+- Send messages to goose and receive responses
+- Get formatted code blocks with syntax highlighting
+- Continue conversations across multiple sessions
+- Access all your configured goose extensions
+
+## Managing Paired Users
+
+From the Desktop app's Gateway settings, you can:
+- View all paired Telegram users
+- See which session each user is connected to
+- Unpair users to revoke their access
+
+## Troubleshooting
+
+### Bot not responding
+- Verify the bot token is correct
+- Check that the gateway is running in goose Desktop
+- Ensure your computer is awake and goose Desktop is open
+
+### Pairing code not working
+- Pairing codes expire after a few minutes—generate a new one
+- Make sure you're sending the code to the correct bot
+
+### Messages not formatting correctly
+- The gateway converts goose's markdown to Telegram-compatible formatting
+- Some complex formatting may be simplified for Telegram compatibility
+
+## Additional Resources
+
+- [Telegram Bot API Documentation](https://core.telegram.org/bots)
+- [Gateway PR #7199](https://github.com/block/goose/pull/7199)