README

A lightweight, modern PHP wrapper for the Telegram Bot API.

Pelegram provides a clean and expressive interface for building Telegram bots with PHP. It includes Telegram API methods, update handling, routing, types, enums, and convenient helpers for working with incoming updates.

Built for simplicity. Built around the Telegram Bot API.

⚠️ Webhook Only

Important: Pelegram is designed to work with Telegram Webhooks only.

Pelegram does not use or support long polling via getUpdates().

Your bot must have a webhook configured so Telegram can deliver updates directly to your application.

This approach makes Pelegram a good fit for:

Production Telegram bots
PHP web applications
REST/API-based architectures
Nginx/Apache deployments
Cloud servers and VPS environments

Telegram Webhook Requirements

Telegram currently supports webhooks on these ports:

443
80
88
8443

If you already have a webhook configured, Pelegram can process the incoming Telegram update directly through your application.

Requirements

PHP 8.1+
Guzzle HTTP 8.x
A publicly accessible HTTPS endpoint for your Telegram webhook

Installation

Install Pelegram using Composer:

composer require miraliog/pelegram

Then load Composer's autoloader:

require_once __DIR__ . '/vendor/autoload.php';

Quick Start

Create your bot and router:

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Miraliog\Pelegram\Bot;
use Miraliog\Pelegram\Router;
use Miraliog\Pelegram\Types\Message;
use Miraliog\Pelegram\Enums\ParseMode;

$bot = new Bot(
    'YOUR_BOT_TOKEN',
    ParseMode::HTML
);

$router = new Router();

$router->onCommand(
    'start',
    function (Message $message) {
        $message->answer('Hello from <b>Pelegram</b>!');
    }
);

$router->onCommand(
    'help',
    function ($update, Bot $bot) {
        $bot->sendMessage(
            $update->chatId(),
            'You sent the help command!'
        );
    }
);

$router->dispatch($bot);

Pelegram handles the incoming Telegram update and dispatches it to the appropriate route.

Handling Commands

Commands can be handled using onCommand():

$router->onCommand(
    'start',
    function (Message $message) {
        $message->answer('Welcome!');
    }
);

You can also access the Bot instance and the full Update object:

$router->onCommand(
    'help',
    function (Update $update, Bot $bot) {
        $bot->sendMessage(
            $update->chatId(),
            'Help message'
        );
    }
);

Pelegram supports dependency injection for route handlers, allowing you to work with the objects you actually need.

Markups

Pelegram provides convenient builders for Telegram reply and inline keyboards.

Reply Keyboard

<?php

use Miraliog\Pelegram\Enums\ButtonStyle;
use Miraliog\Pelegram\Types\Keyboard\KeyboardButton;
use Miraliog\Pelegram\Types\Keyboard\ReplyKeyboardMarkup;

$keyboard = ReplyKeyboardMarkup::make()
    ->row(
        KeyboardButton::make('Start')
            ->style(ButtonStyle::PRIMARY)
    )
    ->row(
        KeyboardButton::make('Help')
            ->style(ButtonStyle::SUCCESS)
    )
    ->resize();

Inline Keyboard

<?php

use Miraliog\Pelegram\Enums\ButtonStyle;
use Miraliog\Pelegram\Types\Keyboard\InlineKeyboardButton;
use Miraliog\Pelegram\Types\Keyboard\InlineKeyboardMarkup;

$keyboard = InlineKeyboardMarkup::make()
    ->row(
        InlineKeyboardButton::make('Pelegram')
            ->url('https://github.com/miraliog/pelegram')
    )
    ->row(
        InlineKeyboardButton::make('Cancel')
            ->callbackData('cancel')
            ->style(ButtonStyle::DANGER)
    );

The builder API is designed to keep keyboard definitions readable without manually constructing Telegram's nested arrays.

Webhook

Pelegram expects Telegram to send updates to your application through a webhook.

A typical webhook endpoint can simply load your bot and dispatch the incoming update:

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Miraliog\Pelegram\Bot;
use Miraliog\Pelegram\Router;

$bot = new Bot('YOUR_BOT_TOKEN');

$router = new Router();

$router->onCommand('start', function ($message) {
    $message->answer('Hello!');
});

$router->dispatch($bot);

Set this file as your Telegram webhook endpoint.

Note: You cannot use getUpdates() while an outgoing webhook is configured for the bot.

Self-Signed Certificates

If you use a self-signed SSL certificate, Telegram requires you to upload the public certificate when setting the webhook.

Pass the absolute path to the certificate file when configuring the webhook.

For normal HTTPS certificates issued by a trusted certificate authority, such as Let's Encrypt, this is not required.

Design Philosophy

Pelegram intentionally stays close to the official Telegram Bot API.

The goal is not to hide Telegram behind a complicated abstraction, but to provide a cleaner and more expressive PHP interface.

Pelegram focuses on

Simple API access
Clean update handling
Lightweight routing
Typed Telegram objects
Fluent keyboard builders
PHP 8.1+ features
Minimal abstraction
Webhook-first architecture

Why Pelegram?

Instead of manually working with raw HTTP requests and deeply nested Telegram arrays, Pelegram gives you a structured interface:

$message->answer('Hello!');

instead of:

$bot->sendMessage(
    $message->chatId(),
    'Hello!'
);

And keyboard definitions can be expressed using a fluent builder:

InlineKeyboardMarkup::make()
    ->row(
        InlineKeyboardButton::make('Open')
            ->url('https://example.com')
    );

The result is bot code that stays close to Telegram while remaining easy to read and maintain.

Telegram Bot API

Pelegram is a PHP wrapper around the official Telegram Bot API.

For the complete Telegram API reference, see:

https://core.telegram.org/bots/api

License

Pelegram is open-source software licensed under the MIT License.

miraliog / pelegram

Package info

Security

Statistics