mirror of
https://github.com/wassname/pi-telegram.git
synced 2026-07-21 12:40:49 +08:00
167 lines
3.5 KiB
Markdown
167 lines
3.5 KiB
Markdown
# pi-telegram
|
|
|
|
|
|
|
|
> Full pi build session: [View the session transcript](https://pi.dev/session/#14acfe07b7844c8abec55ed9fbddc17f), which captures the full pi session in which `pi-telegram` was built.
|
|
|
|
Telegram DM bridge for pi.
|
|
|
|
## Install
|
|
|
|
From git:
|
|
|
|
```bash
|
|
pi install git:github.com/llblab/pi-telegram
|
|
```
|
|
|
|
Or for a single run:
|
|
|
|
```bash
|
|
pi -e git:github.com/llblab/pi-telegram
|
|
```
|
|
|
|
## Configure
|
|
|
|
### Telegram
|
|
|
|
1. Open [@BotFather](https://t.me/BotFather)
|
|
2. Run `/newbot`
|
|
3. Pick a name and username
|
|
4. Copy the bot token
|
|
|
|
### pi
|
|
|
|
Start pi, then run:
|
|
|
|
```bash
|
|
/telegram-setup
|
|
```
|
|
|
|
Paste the bot token when prompted.
|
|
|
|
The extension stores config in:
|
|
|
|
```text
|
|
~/.pi/agent/telegram.json
|
|
```
|
|
|
|
## Connect a pi session
|
|
|
|
The Telegram bridge is session-local. Connect it only in the pi session that should own the bot:
|
|
|
|
```bash
|
|
/telegram-connect
|
|
```
|
|
|
|
To stop polling in the current session:
|
|
|
|
```bash
|
|
/telegram-disconnect
|
|
```
|
|
|
|
Check status:
|
|
|
|
```bash
|
|
/telegram-status
|
|
```
|
|
|
|
## Pair your Telegram account
|
|
|
|
After token setup and `/telegram-connect`:
|
|
|
|
1. Open the DM with your bot in Telegram
|
|
2. Send `/start`
|
|
|
|
The first DM user becomes the allowed Telegram user for the bridge. The extension only accepts messages from that user.
|
|
|
|
## Usage
|
|
|
|
Chat with your bot in Telegram DMs.
|
|
|
|
### Send text
|
|
|
|
Send any message in the bot DM. It is forwarded into pi with a `[telegram]` prefix.
|
|
|
|
### Send images and files
|
|
|
|
Send images, albums, or files in the DM.
|
|
|
|
The extension:
|
|
|
|
- downloads them to `~/.pi/agent/tmp/telegram`
|
|
- includes local file paths in the prompt
|
|
- forwards inbound images as image inputs to pi
|
|
|
|
### Ask for files back
|
|
|
|
If you ask pi for a file or generated artifact, pi should call the `telegram_attach` tool. The extension then sends those files with the next Telegram reply.
|
|
|
|
Examples:
|
|
|
|
- `summarize this image`
|
|
- `read this README and summarize it`
|
|
- `write me a markdown file with the plan and send it back`
|
|
- `generate a shell script and attach it`
|
|
|
|
### Stop a run
|
|
|
|
In Telegram, send:
|
|
|
|
```text
|
|
stop
|
|
```
|
|
|
|
or:
|
|
|
|
```text
|
|
/stop
|
|
```
|
|
|
|
That aborts the active pi turn.
|
|
|
|
### Queue follow-ups
|
|
|
|
If you send more Telegram messages while pi is busy, they are queued and processed in order.
|
|
|
|
The pi status bar shows queued Telegram turns as compact previews, for example:
|
|
|
|
```text
|
|
+3: [summarize this image…, write a shell script…, 📎 2 attachments]
|
|
```
|
|
|
|
Each preview is limited to at most 5 words or 40 characters.
|
|
|
|
### Reprioritize or discard queued messages
|
|
|
|
While a message is still waiting in the queue:
|
|
|
|
- React with 👍 to move it into the priority block
|
|
- React with 👎 to remove it from the queue
|
|
|
|
Priority is stable:
|
|
|
|
- The first liked queued message stays ahead of later liked messages
|
|
- Removing 👍 sends the message back to its normal queue position
|
|
- Adding 👍 again gives it a fresh priority position
|
|
|
|
For media groups, a reaction on any message in the group applies to the whole queued turn.
|
|
|
|
Message reactions depend on Telegram delivering `message_reaction` updates for your bot and chat type.
|
|
|
|
## Streaming
|
|
|
|
The extension streams assistant text previews back to Telegram while pi is generating.
|
|
|
|
It tries Telegram draft streaming first with `sendMessageDraft`. If that is not supported for your bot, it falls back to `sendMessage` plus `editMessageText`.
|
|
|
|
## Notes
|
|
|
|
- Only one pi session should be connected to the bot at a time
|
|
- Replies are sent as normal Telegram messages, not quote-replies
|
|
- Long replies are split below Telegram's 4096 character limit
|
|
- Outbound files are sent via `telegram_attach`
|
|
|
|
## License
|
|
|
|
MIT
|