fahriztx/telman

Laravel package for Telegram Manager API client with webhook handler

v0.0.2 2026-05-29 16:45 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/http: ^10.0|^11.0
• illuminate/support: ^10.0|^11.0

MIT

• Fahri

README

A Laravel package that provides a clean client and webhook handler for the Telegram Manager API. Instead of using bot tokens directly, this package routes requests through a Telegram Manager proxy.

Installation

composer require fahriztx/telman

Configuration

Publish the config file:

php artisan vendor:publish --tag=telman-config

Add the following to your .env:

TELMAN_BASE_URL=https://your-host/api/v1
TELMAN_API_KEY=tgm_live_your_api_key
TELMAN_BOT_ID=your_bot_id
TELMAN_WEBHOOK_SECRET=your_webhook_secret

Config Options

Key	Description	Default
base_url	Telegram Manager API base URL	https://your-host/api/v1
api_key	API key for authentication	null
bot_id	Bot ID for requests	null
webhook_secret	Secret for webhook signature verification	null
webhook_prefix	URL prefix for webhook routes	telman
enable_webhook	Auto-register webhook routes	true

Usage

Sending Messages

use Fahriztx\Telman\TelmanFacade as Telman;

// Simple text message
Telman::text(123456789, 'Hello from Laravel!');

// With inline keyboard
Telman::sendMessage([
    'chat_id' => 123456789,
    'text' => 'Order #2437234 confirmed!',
    'reply_markup' => Telman::inlineKeyboard([
        [['text' => 'Open', 'url' => 'https://example.com/order/2437234']],
    ]),
]);

// With callback buttons (JSON-encoded callback_data)
Telman::sendMessage([
    'chat_id' => 123456789,
    'text' => 'Confirm order #2437234?',
    'reply_markup' => Telman::inlineKeyboard([
        [
            ['text' => 'Yes', 'callback_data' => json_encode(['orderId' => '2437234', 'status' => 'confirm'])],
            ['text' => 'No', 'callback_data' => json_encode(['orderId' => '2437234', 'status' => 'reject'])],
        ],
    ]),
]);

Sending Photos (Multipart)

Telman::sendPhotoMultipart([
    'chat_id' => 123456789,
    'caption' => 'Here is your photo',
], '/path/to/photo.jpg');

Dynamic Method Calls

Any Telegram Bot API method can be called dynamically:

// sendMessage
Telman::sendMessage([
    'chat_id' => 123456789,
    'text' => 'Hello!',
]);

// editMessageText
Telman::editMessageText([
    'chat_id' => 123456789,
    'message_id' => 42,
    'text' => 'Updated text!',
]);

// deleteMessage
Telman::deleteMessage([
    'chat_id' => 123456789,
    'message_id' => 42,
]);

Webhook Handler

The webhook route is automatically registered at POST /{webhook_prefix}/webhook (default: /telman/webhook).

Registering Callback Handlers

Callback data is expected to be JSON-encoded with a status field for routing:

use Fahriztx\Telman\WebhookHandler;
use Fahriztx\Telman\TelmanFacade as Telman;

// Handler for confirm status
WebhookHandler::on('confirm', function ($data, $update) {
    $orderId = $data['orderId'];
    Order::where('id', $orderId)->update(['status' => 'confirmed']);

    Telman::sendMessage([
        'chat_id' => $update['callback_query']['from']['id'],
        'text' => "Order #{$orderId} confirmed! ✅",
    ]);
});

// Handler for reject status
WebhookHandler::on('reject', function ($data, $update) {
    $orderId = $data['orderId'];
    Order::where('id', $orderId)->update(['status' => 'rejected']);

    Telman::sendMessage([
        'chat_id' => $update['callback_query']['from']['id'],
        'text' => "Order #{$orderId} rejected. ❌",
    ]);
});

// Fallback for all unhandled callbacks
WebhookHandler::on('*', function ($data, $update) {
    \Illuminate\Support\Facades\Log::info('Unhandled callback: ' . json_encode($data));
});

// Handle incoming messages
WebhookHandler::handleMessage(function ($message, $update) {
    \Illuminate\Support\Facades\Log::info('Message: ' . $message['text']);
});

Setting Up Webhook in Telegram Manager

Point your Telegram Manager webhook URL to:

https://your-app.com/telman/webhook

(Or whatever prefix you configured in webhook_prefix.)

Rate Limit Handling

use Fahriztx\Telman\TelmanException;

try {
    Telman::sendMessage([...]);
} catch (TelmanException $e) {
    if ($e->retryAfter()) {
        sleep($e->retryAfter());
        Telman::sendMessage([...]);
    }
}

Disabling Webhook Routes

Set enable_webhook to false in your config:

// config/telman.php
return [
    'enable_webhook' => false,
];

Exception Handling

The TelmanException provides access to the full API response parameters:

use Fahriztx\Telman\TelmanException;

try {
    Telman::sendMessage([...]);
} catch (TelmanException $e) {
    // Error description
    echo $e->getMessage();

    // HTTP status code
    echo $e->getCode();

    // Retry-after value (if rate limited)
    if ($retryAfter = $e->retryAfter()) {
        echo "Retry after {$retryAfter} seconds";
    }

    // Full response parameters
    $params = $e->parameters;
}

License

MIT