Skip to content
Telegram bot api Laravel package

Handling Messages

Handling text messages is one of the core functions of a Telegram bot. The package provides flexible capabilities for working with messages.

Basic Usage

Section titled “Basic Usage”

All Messages

Section titled “All Messages”
use HybridGram\Facades\TelegramRouter;
use HybridGram\Core\Routing\RouteData\TextTextMessageData;


TelegramRouter::onTextMessage(function(TextTextMessageData $data) {
    $text = $data->text; // Message text (string)
    $chatId = $data->getChat()->id;


    $telegram = app(\HybridGram\Telegram\TelegramBotApi::class);
    $telegram->sendMessage($chatId, "You wrote: {$text}");
});

Messages by Pattern

Section titled “Messages by Pattern”

Check message text by string pattern:

// Exact match
TelegramRouter::onTextMessage(function(TextMessageData $data) {
    // ...
}, '*', 'hello');


// With wildcard (Laravel Str::is)
TelegramRouter::onTextMessage(function(TextMessageData $data) {
    // Triggers for: "hello", "hello everyone", "say hello"
}, '*', 'hello*');

Custom Check via Closure

Section titled “Custom Check via Closure”

For complex logic, use closures:

TelegramRouter::onTextMessage(function(TextMessageData $data) {
    // Processing
}, '*', function(TextMessageData $data) {
    // Return true if route should trigger
    $text = $data->text;


    // Check length
    if (strlen($text) < 10) {
        return false;
    }


    // Check for keywords
    $keywords = ['order', 'delivery', 'payment'];
    return str_contains($text, $keywords);
});

Accessing Message Data

Section titled “Accessing Message Data”

The TextMessageData object contains:

TelegramRouter::onTextMessage(function(TextMessageData $data) {
    // Message text (string)
    $text = $data->text;


    // Full Message object from Telegram API
    $messageObject = $data->message;


    // Full Update object
    $update = $data->update;


    // Chat and User
    $chat = $data->getChat();
    $user = $data->getUser();


    // Additional info from message
    $messageId = $messageObject->messageId;
    $date = $messageObject->date;
    $entities = $messageObject->entities; // Text formatting
});

Working with Formatting

Section titled “Working with Formatting”

Telegram supports various formatting types in messages:

TelegramRouter::onTextMessage(function(TextMessageData $data) {
    $message = $data->message;


    // Check for formatting
    if ($message->entities !== null) {
        foreach ($message->entities as $entity) {
            if ($entity->type === 'bold') {
                // Handle bold text
            }
            if ($entity->type === 'code') {
                // Handle code
            }
        }
    }
});

Messages in State Context

Section titled “Messages in State Context”

Messages are often processed depending on current state:

TelegramRouter::onTextMessage(function(TextMessageData $data) {
    $stateManager = app(\HybridGram\Core\State\StateManagerInterface::class);
    $chat = $data->getChat();


    $currentState = $stateManager->getChatState($chat);


    if ($currentState?->getName() === 'awaiting_name') {
        // User is entering name
        $name = $data->message;
        // Save name and proceed to next step
    }
}, '*', function(TextMessageData $data) {
    // Check if in "awaiting name" state
    $stateManager = app(\HybridGram\Core\State\StateManagerInterface::class);
    $chat = $data->getChat();
    $state = $stateManager->getChatState($chat);


    return $state?->getName() === 'awaiting_name';
});

Filtering by Chat Types

Section titled “Filtering by Chat Types”

You can filter messages by chat type:

TelegramRouter::forBot('main')
    ->onTextMessage(function(TextMessageData $data) {
        // Private chats only
    })
    ->whereChatType('private');

Usage Examples

Section titled “Usage Examples”

Echo Bot

Section titled “Echo Bot”
TelegramRouter::onTextMessage(function(TextMessageData $data) {
    $telegram = app(\HybridGram\Telegram\TelegramBotApi::class);
    $telegram->sendMessage(
        $data->getChat()->id,
        "You wrote: {$data->message}"
    );
});
Section titled “Keyword Search”
TelegramRouter::onTextMessage(function(TextMessageData $data) {
    $text = strtolower($data->message);
    $chatId = $data->getChat()->id;
    $telegram = app(\HybridGram\Telegram\TelegramBotApi::class);


    if (str_contains($text, 'weather')) {
        $telegram->sendMessage($chatId, 'Fetching weather forecast...');
        // ...
    } elseif (str_contains($text, 'rate')) {
        $telegram->sendMessage($chatId, 'Fetching exchange rates...');
        // ...
    }
}, '*', function(TextMessageData $data) {
    $keywords = ['weather', 'rate', 'news'];
    $text = strtolower($data->message);
    return str_contains($text, $keywords);
});

Handling Long Messages

Section titled “Handling Long Messages”
TelegramRouter::onTextMessage(function(TextMessageData $data) {
    $text = $data->message;


    // Split long message into parts
    if (strlen($text) > 4096) {
        $chunks = str_split($text, 4090);
        $telegram = app(\HybridGram\Telegram\TelegramBotApi::class);


        foreach ($chunks as $chunk) {
            $telegram->sendMessage($data->getChat()->id, $chunk);
        }
    }
}, '*', function(TextMessageData $data) {
    return strlen($data->message) > 4096;
});

Handling Message Replies

Section titled “Handling Message Replies”

For handling replies to messages, use the special route:

use HybridGram\Core\Routing\RouteData\ReplyData;


TelegramRouter::onReply(function(ReplyData $data) {
    $originalMessage = $data->update->message->replyToMessage;
    $replyText = $data->update->message->text;


    // Process reply
});

What’s Next?

Section titled “What’s Next?”