Skip to content

Telegram: bot commands and chats as playlists #686

Open

Description

@cartudev

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.getBotCommands over 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.forwardMessages to 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:

  1. Visibility in cliamp: already handled. Only audio documents become tracks, so text commands never show in the list. Nothing to do here.
  2. 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. U and Ctrl+P are 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

  1. cartudev commented on Nov 5, 2026

    @cartudev
    ContributorAuthor

    @bjarneo could you add the enhancement and help wanted labels when you triage this? My account cannot set labels in this repository.

  2. cartudev commented on Nov 16, 2026

    @cartudev
    ContributorAuthor

    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.

    PR Scope
    #726 Telegram write transport: bot commands, send, wait reply/audio, callbacks, message, resolve, inline results
    #727 Plugin action pane (!), cliamp.provider.*, queue.insert, basic ui.input, a generic Telegram bot example
    #728 Live inputs, ui.suggestions, rich selector rows with images, ui.text, inline/message actions
    #729 Provider sections, action context, provider.open, telegram.resolve, telegram.add_chat, Ctrl+C over plugin panes

    The DeezLoad-specific flow is not in the core. It lives in cartudev/cliamp-plugin-deezload: command palette, @DeezLoadApp inline search, covers, reply history, .trk/.art, TOP 30 and the settings panel. The core only carries generic APIs; the bundled telegram-bot.lua is a small generic example.

    Each branch passes go test ./... and go 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

    • Bot commands: yes. bots.getBotCommands feeds the command menu; messages.sendMessage sends 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 through on_reply.
    • Suggestions: yes, from the bot commands, from live inline results, and from the plugin's own stored replies. The config-file list and a per-chat command history are still open.
    • Chats as playlists: read side already existed; the write side can now send into a chat, so a bot chat works as an authoring surface. Copy/move between chats is still open.
    • Visibility in cliamp: text commands never become tracks; only audio documents do, so the playlist stays clean.
    • Plugin split: implemented as proposed: provider actions behind provider-send, UI in a plugin, no DeezLoad code upstream.

    Still open

    Capability Needs Notes
    Search in chat messages.search Independent and low risk; can land before copy/move
    Copy / save messages.forwardMessages Save to Saved Messages is the same call with self
    Move / remove track forward + deleteMessages Destructive; confirm and dry run
    Cleanup deleteMessages 48-hour delete-for-everyone window, admin rules, dry run
    Add bot to a group messages.addChatUser / channels.inviteToChannel Needs admin permissions and a visibility warning
    Create group as playlist messages.createChat Then copy into it
    Rate limiting pacing + FLOOD_WAIT on writes Reads retry today; writes return the error
    Command history store per chat Small addition to the plugin, not the provider

    Defaults I would propose

    • Copy by default, move explicit. Move is forward plus delete and needs a confirmation that names the source chat; it should not be the default.
    • Cleanup off by default. When enabled: dry run first, show the exact message count and the 48-hour limitation, and never delete in a group unless the account is an admin and the user confirms the member-visible effect.
    • Search filters the existing chat, not the whole account. It should reuse the peer and return audio documents like the normal track page.
    • Groups stay opt-in. Adding the bot, writing in a group and deleting there are three separate permissions in practice, even if the API has one write permission.

    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

    1. Should cleanup delete both the command and the bot reply, or only the command?
    2. Should a move keep the "forwarded from" header, or send a copy without it?
    3. For groups, should cliamp refuse to write unless the bot is already a member, or offer to invite it first?
    4. Is a per-chat command history worth storing, or are bot commands plus inline results enough?

    Happy to adjust the stack or fold PRs together if you prefer a different review shape.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions