Repository navigation
Description
Summary
The Telegram provider reads chats and plays their audio. It does not write: there is no way to ask a music bot for a track, and no way to build a playlist by moving audio between chats.
This proposes the write side, keeping everything inside the chat:
- send bot commands from the Telegram pane, with a prompt and suggestions
- use a chat or group as a playlist, copying or moving audio between chats
- optional history cleanup, so command and response messages do not pile up
Why
Music bots are how a large part of Telegram listens to music. DeezLoad alone shows 282,767 monthly users. Today cliamp can play what those bots already posted, but it cannot ask for a new track. The user leaves cliamp, opens Telegram, types the command, comes back and reloads.
The chat is already the playlist: TracksPage walks messages.getHistory and keeps the audio documents. The missing piece is authoring.
Bot commands
In the Telegram pane, / (or !) opens a prompt. The command goes out as the user through MTProto (messages.sendMessage), not through the Bot API. That matters: a music bot answers users, not other bots.
Suggestions can come from:
- the commands the bot advertises (
bots.getBotCommandsover MTProto) - commands sent from cliamp before, per chat
- a list in
config.toml, per chat - the dialogs already selected in
chats, so the first suggestions are the bots the user actually uses (in my case, the two I have)
The response is a normal message in the chat. The provider already turns audio documents into tracks, so the new track appears in the pane on the next page load. No new transport.
Open questions:
- should the prompt be a pane, an overlay, or a line above the track list?
- does
/collide with an existing key?!is the fallback. - should cliamp reload the chat after a command, and how long should it wait for the bot?
Chats as playlists
A chat is already a playlist: the provider lists its audio documents. What is missing is moving tracks between lists:
- copy:
messages.forwardMessagesto another chat, keeping the file - move: forward, then delete the original. Destructive, so opt-in and confirmed
- save: forward to Saved Messages as a personal playlist
- create: a new group as an empty playlist, then copy into it
This maps the playlist operations of other providers onto messages, and gives a use to groups that exist only to collect music.
Open questions:
- copy or move by default?
- keep the "forwarded from" header, or send a copy without it?
- what happens when the source message is deleted later? The copied document survives; a cached path does not.
History cleanup
Command and response messages accumulate. There are two separate problems:
- Visibility in cliamp: already handled. Only audio documents become tracks, so text commands never show in the list. Nothing to do here.
- The chat itself: the messages stay in Telegram. Options:
- delete the command and the bot's reply after the track is added
- keep everything from the current request onward, delete what came before
- delete nothing (default)
Deleting is irreversible and, in a group, affects other members. It only works for messages the account may delete: its own, or any message when it is an admin. Telegram also limits delete-for-everyone to a window (48 hours for users); older messages disappear only for the account.
This should be opt-in per chat, with a confirmation that lists how many messages would go, and a dry run first.
Parity with other providers
| Capability | Other providers | Telegram today | Proposal |
|---|---|---|---|
| list playlists | yes | chats | already |
| play tracks | yes | yes | already |
| search | yes | no | search the selected chat (messages.search) |
| add track | yes | no | send a bot command, or copy an audio message |
| create playlist | yes | no | create a group |
| remove track | yes | no | delete the message (with the caveats above) |
Search within the selected chat is a smaller, independent win: MTProto has messages.search, and the provider already has the peer.
Consequences
- Account automation. Sending a command looks like a normal client. Bulk forwarding and deleting look like spam. Expect
FLOOD_WAIT, and in the worst case a limitation on the account. Any bulk operation needs pacing and a clear warning. - Visibility. A command sent to a group is visible to every member. Users should know before cliamp writes in a shared chat.
- Irreversible deletes. A wrong cleanup deletes messages for everyone. Confirmation and a dry run are not optional.
- Bot variance. Bots answer in different ways: text, audio, buttons, or a callback that needs a button press. Some will not work with a plain text command at all.
- Threat model. Today the provider is read-only. Adding writes means the session file grants more: sending and deleting as the user. That deserves a line in the docs.
- Testing. The provider holds a concrete
*tg.Client. Write operations need an interface or a fake server to test without a real account. - Keymap.
UandCtrl+Pare taken. A command prompt needs a key that does not collide, and a way to discover it.
Could a plugin do this instead?
The plugin API today gives a sandboxed Lua VM: panes, images, selectors, keymaps, events, cliamp.http for public endpoints, and fs/exec behind permissions. It does not expose the Telegram client or the session.
A plugin can talk to the Bot API with its own token, but that does not solve the problem:
- a bot does not receive messages from another bot, so it cannot drive a music bot that expects a user
- the Bot API cannot read the account's dialog history or act as the user
- the plugin cannot reuse the MTProto session the provider already has
So a plugin can draw the interface, but not perform the action.
If the concern is keeping the UI out of the core, the split could be:
- the provider exposes actions (send, forward, delete) over a small API
- the plugin draws the command palette and calls them, behind a new permission
That still requires the core to implement and permission the write path. It is more work than doing it in the provider, and it enlarges the permission surface rather than shrinking it. The plugin-only path is limited to bots the user owns, through the Bot API.
Suggestions welcome
This is a proposal, not a fixed design. The parts I am least sure about: the default for copy versus move, how much cleanup is safe to offer, and whether the command UI belongs in the provider pane or in a plugin once the actions exist.
Activity
cartudev commentedon Nov 5, 2026
@bjarneo could you add the
enhancementandhelp wantedlabels when you triage this? My account cannot set labels in this repository.cartudev commentedon Nov 16, 2026
Status
The write path is implemented and split into a stack of PRs. The stack is intentionally layered so the transport can be reviewed without the plugin API, and the plugin API without the DeezLoad-specific flow.
!),cliamp.provider.*,queue.insert, basicui.input, a generic Telegram bot exampleui.suggestions, rich selector rows with images,ui.text, inline/message actionsprovider.open,telegram.resolve,telegram.add_chat,Ctrl+Cover plugin panesThe DeezLoad-specific flow is not in the core. It lives in cartudev/cliamp-plugin-deezload: command palette,
@DeezLoadAppinline search, covers, reply history,.trk/.art, TOP 30 and the settings panel. The core only carries generic APIs; the bundledtelegram-bot.luais a small generic example.Each branch passes
go test ./...andgo vet ./.... All four PRs are ready for review; they are stacked and will be rebased as the earlier ones land. CodeRabbit already reviewed the transport and action layers; the findings are fixed in the branches.What is covered from the proposal
bots.getBotCommandsfeeds the command menu;messages.sendMessagesends as the signed-in user; the reply can be text, audio or buttons. Waiting is bounded by a timeout and runs off the UI goroutine throughon_reply.provider-send, UI in a plugin, no DeezLoad code upstream.Still open
messages.searchmessages.forwardMessagesselfdeleteMessagesdeleteMessagesmessages.addChatUser/channels.inviteToChannelmessages.createChatFLOOD_WAITon writesDefaults I would propose
Security note
Writes use the same MTProto session as reads and act as the signed-in user. A bot sees a normal message from the account; a command sent to a group is visible to every member. The session file now grants more than reading, and the docs in #726/#727 say so. A plugin needs
provider-send; the action pane is a user gesture, not an automatic send.Open questions
Happy to adjust the stack or fold PRs together if you prefer a different review shape.