> ## Documentation Index
> Fetch the complete documentation index at: https://help.bots.lt/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Routing

> How to handle user messages, events, and wildcards using BLP commands.

In Bots.LT, every piece of logic is triggered by a **Command**. A command is a specific string or pattern that the platform listens for from the Telegram API.

***

## Command Types

### 1. Exact Match Commands

The most common type of command. If a user types exactly this string, the corresponding code executes.

| Command Name | Description                                                         |
| ------------ | ------------------------------------------------------------------- |
| `/start`     | Triggered when a user starts the bot.                               |
| `/help`      | Triggered when a user types `/help`.                                |
| `Menu`       | Triggered when a user sends the exact text "Menu" (case-sensitive). |

***

### 2. Wildcard Command (`*`)

The `*` command acts as a **catch-all**. It catches **any text message** that doesn't match an exact command.

**Common Use Cases:**

* Chatbots using AI (ChatGPT/Gemini) that need to process natural language.
* Catch-all fallback messages ("I don't understand that command.").
* Tracking user state or processing conversational inputs.

```python BLP Example (AI Chatbot) theme={null}
# Inside the * command
user_text = message.text

# Process with AI (pseudo-code)
# response = call_ai_api(user_text)

Bot.sendMessage(chat_id=u, text="You said: " + user_text)
```

***

### 3. Before All Command (`@`)

The `@` command is a special **middleware** command. If it exists, it runs **before any other command**.

**Common Use Cases:**

* Checking if a user is banned globally.
* Enforcing channel membership (Force Sub).
* Logging user activity before processing their request.

> **Important:** If you call `ReturnCommand()` inside the `@` command, the execution stops immediately, and the actual triggered command will **not** run.

```python BLP Example (Ban Check Middleware) theme={null}
# Inside the @ command

banned = User.getData("banned")
if banned == "true":
    Bot.sendMessage(chat_id=u, text="🚫 You are banned from using this bot.")
    ReturnCommand() # Stops execution here. The target command won't run.

# If not banned, the script naturally finishes and the target command executes.
```

***

## Special Event Handlers

Aside from text messages, Telegram sends other types of updates (like button clicks, photo uploads, or new members joining). Bots.LT maps these events to special built-in command names.

| Event Command               | Trigger Condition                      | Available Context                                |
| --------------------------- | -------------------------------------- | ------------------------------------------------ |
| `/handler_callback_query`   | User clicks an `InlineKeyboardButton`. | `call.data` contains the callback string.        |
| `/handler_photo`            | User sends a photo.                    | `message.photo` contains the photo array.        |
| `/handler_video`            | User sends a video.                    | `message.video` contains the video object.       |
| `/handler_document`         | User sends a file/document.            | `message.document` contains the document object. |
| `/handler_audio`            | User sends an audio file.              | `message.audio` contains the audio object.       |
| `/handler_voice`            | User sends a voice note.               | `message.voice` contains the voice object.       |
| `/handler_new_chat_members` | Someone joins a group.                 | `message.new_chat_members` array.                |
| `/handler_left_chat_member` | Someone leaves a group.                | `message.left_chat_member` object.               |
| `/handler_my_chat_member`   | The bot is added/removed from a group. | `message.my_chat_member` object.                 |

```python BLP Example (Handling Callbacks) theme={null}
# Inside /handler_callback_query

data = call.data

if data == "btn_accept":
    Bot.answerCallbackQuery(callback_query_id=call.id, text="Accepted!")
    Bot.sendMessage(chat_id=u, text="You accepted the terms.")
```

```python BLP Example (Handling Photos) theme={null}
# Inside /handler_photo

# The photo array contains different sizes. The last one is the highest quality.
photo_id = message.photo[-1].file_id

Bot.sendMessage(chat_id=u, text=f"Nice photo! The file ID is: {photo_id}")
```