How to use VibeGuard MusicFind as a Telegram music search bot

MusicFind is an optional community feature. It works best after your group already has the basics under control: safety, moderation, and clear admin settings.

Each Telegram group keeps its own MusicFind settings, permissions, post records, cached results, and provider configuration. One creator fan chat can allow members to search freely, while a stricter marketplace or public group can keep music posting admin-only.

Before you start, decide two things: who can search, and who can post into the group. Search can be lightweight and social. Posting should be controlled so the chat does not get buried under tracks, repeated links, or provider errors.

MusicFind supports three practical permission modes.

Open lets everyone search, while posting stays admin-only.

Semi-open lets everyone search, while admins and allowlisted members can post.

Closed keeps both search and posting limited to admins.

For most communities, semi-open is the best starting point. Members can discover tracks, but admins decide who is trusted enough to post results into the group.

Settings are admin-only. Allowlist changes should be handled by admins or owners, not by normal members.

Use /search <query> when you want MusicFind to return a result list without automatically posting a track.

MusicFind normalizes the query, checks enabled providers, applies provider timeouts, ranks results, removes near-duplicates, and returns a short list. Results can show the track title, artist, duration, provider, and available actions.

A typical result can include buttons for posting, viewing details, opening an external link when available, or canceling the search session.

Use /song <query> when your group has configured a faster song lookup or post-oriented flow. Posting still depends on the group mode, the actor’s permissions, and provider availability.

Use /post <query> or a result button when a permitted user wants to share a track in the group.

MusicFind checks the group mode and the actor before posting. If compliant audio delivery is available, MusicFind can prefer a Telegram audio post using an authorized audio URL or a cached Telegram file ID. If audio delivery is not available or fails, it can fall back to a link post.

That fallback is normal. MusicFind should not silently switch to non-compliant behavior just because a provider is unavailable or a track cannot be sent as audio.

Every post should leave an audit-friendly record with the track metadata, posting actor, provider context, and result state.

Use /settings to review or change MusicFind configuration for the group.

Use /allow @username, /allow ID, or /allow name to let a trusted member post in semi-open mode. Use /deny with the same target types to remove posting access.

When possible, MusicFind resolves allowlist targets through the group member directory. If the target cannot be resolved that way, it can fall back to known local usernames or numeric IDs.

Keep the allowlist short. It is better to let many members search and only a few trusted members post.

MusicFind is for compliant music discovery, not unauthorized downloads.

The provider layer should only use documented and authorized provider APIs. MusicFind should not scrape music sites, generate unofficial tokens, impersonate clients, reverse-engineer authentication flows, or post copyrighted downloads without authorization.

When a provider is unavailable, the expected behavior is a clear provider-unavailable message and a configuration hint. That is better than a hidden fallback that puts the group or bot at risk.

Expected result:

After setup, members can search within the limits your admins choose. Trusted users can post when the group mode allows it. Provider failures are visible. Audio delivery uses authorized paths when available, and link fallback is used when audio is not available.

Troubleshooting:

Problem: Members can search but cannot post. Fix: Check the group mode. In open mode, posting is admin-only. In semi-open mode, the member must be an admin or allowlisted.

Problem: A track posted as a link instead of audio. Fix: The provider may not expose authorized audio delivery, or the audio send may have failed. Link fallback is expected.

Problem: Search results are empty. Fix: Try a more specific query, check enabled providers, and review provider timeout or availability status.

Problem: /allow did not find the member. Fix: Try a username, numeric Telegram ID, or a name that exists in the group’s known member directory.

Problem: A provider is unavailable. Fix: Check provider configuration. MusicFind should show a clear unavailable message instead of using non-compliant fallbacks.