Build Interactive Telegram Inline Keyboards in PHP

<?php

declare(strict_types=1);

function sendTelegramRequest(string $method, array $payload): array
{
    $botToken = getenv('TELEGRAM_BOT_TOKEN');
    if (!$botToken) {
        throw new RuntimeException('TELEGRAM_BOT_TOKEN environment variable is not set.');
    }

    $url = sprintf('https://api.telegram.org/bot%s/%s', $botToken, $method);
    $ch = curl_init($url);

    $jsonPayload = json_encode($payload);

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => $jsonPayload,
        CURLOPT_TIMEOUT => 10,
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error = curl_error($ch);
    curl_close($ch);

    if ($response === false) {
        throw new RuntimeException('cURL request failed: ' . $error);
    }

    $decoded = json_decode($response, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new RuntimeException('Failed to decode Telegram response JSON: ' . json_last_error_msg());
    }

    if ($httpCode !== 200 || !isset($decoded['ok']) || $decoded['ok'] !== true) {
        $description = $decoded['description'] ?? 'Unknown error';
        throw new RuntimeException(sprintf('Telegram API error (%d): %s', $httpCode, $description));
    }

    return $decoded['result'];
}

function sendInlineMenu(int|string $chatId, string $text): array
{
    $keyboard = [
        'inline_keyboard' => [
            [
                ['text' => 'Option A', 'callback_data' => 'opt:a'],
                ['text' => 'Option B', 'callback_data' => 'opt:b'],
            ],
            [
                ['text' => 'Refresh Menu', 'callback_data' => 'ref:main'],
            ]
        ]
    ];

    return sendTelegramRequest('sendMessage', [
        'chat_id' => $chatId,
        'text' => htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
        'parse_mode' => 'HTML',
        'reply_markup' => $keyboard,
    ]);
}

<?php

declare(strict_types=1);

function answerCallbackQuery(string $callbackQueryId, ?string $text = null, bool $showAlert = false): array
{
    $payload = [
        'callback_query_id' => $callbackQueryId,
    ];

    if ($text !== null) {
        $payload['text'] = $text;
        $payload['show_alert'] = $showAlert;
    }

    return sendTelegramRequest('answerCallbackQuery', $payload);
}

<?php

declare(strict_types=1);

function updateMenuState(int|string $chatId, int $messageId, string $newText, array $newKeyboard): array
{
    return sendTelegramRequest('editMessageText', [
        'chat_id' => $chatId,
        'message_id' => $messageId,
        'text' => htmlspecialchars($newText, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
        'parse_mode' => 'HTML',
        'reply_markup' => $newKeyboard,
    ]);
}

<?php

declare(strict_types=1);

// Read incoming JSON body from Telegram Webhook
$rawInput = file_get_contents('php://input');
if (!$rawInput) {
    http_response_code(400);
    exit('Empty payload');
}

$update = json_decode($rawInput, true);
if (json_last_error() !== JSON_ERROR_NONE || !is_array($update)) {
    http_response_code(400);
    exit('Invalid JSON');
}

// Handle Callback Queries
if (isset($update['callback_query'])) {
    $callbackQuery = $update['callback_query'];
    $callbackId    = $callbackQuery['id'];
    $callbackData  = $callbackQuery['data'] ?? '';
    $message       = $callbackQuery['message'] ?? null;

    if (!$message) {
        // Handled inline message or obsolete callback
        answerCallbackQuery($callbackId, 'Message context unavailable.');
        exit;
    }

    $chatId    = $message['chat']['id'];
    $messageId = $message['message_id'];

    // Parse delimited payload (e.g. "act:value")
    $parts  = explode(':', $callbackData, 2);
    $action = $parts[0] ?? '';
    $param  = $parts[1] ?? '';

    try {
        switch ($action) {
            case 'opt':
                // Acknowledge the press via Toast banner
                answerCallbackQuery($callbackId, "Selected option " . strtoupper($param));

                $updatedText = sprintf("Current state: <b>Option %s</b> selected.", strtoupper($param));
                $nextKeyboard = [
                    'inline_keyboard' => [
                        [
                            ['text' => 'Switch to A', 'callback_data' => 'opt:a'],
                            ['text' => 'Switch to B', 'callback_data' => 'opt:b'],
                        ],
                        [
                            ['text' => 'Reset', 'callback_data' => 'ref:main'],
                        ]
                    ]
                ];

                updateMenuState($chatId, $messageId, $updatedText, $nextKeyboard);
                break;

            case 'ref':
                answerCallbackQuery($callbackId, "Menu refreshed", false);

                $resetText = "Main Menu. Select an option below:";
                $defaultKeyboard = [
                    'inline_keyboard' => [
                        [
                            ['text' => 'Option A', 'callback_data' => 'opt:a'],
                            ['text' => 'Option B', 'callback_data' => 'opt:b'],
                        ]
                    ]
                ];

                updateMenuState($chatId, $messageId, $resetText, $defaultKeyboard);
                break;

            default:
                answerCallbackQuery($callbackId, "Unknown action", true);
                break;
        }
    } catch (Throwable $e) {
        // Log error locally and provide non-blocking feedback to user
        error_log('Callback processing error: ' . $e->getMessage());
        answerCallbackQuery($callbackId, "An error occurred while processing your selection.", true);
    }

    http_response_code(200);
    echo 'OK';
    exit;
}

// Non-callback updates can be handled here...
http_response_code(200);
echo 'OK';