DEV Community: Serhii

Authenticate React Telegram Mini Apps with InitData and JWT

Serhii — Tue, 22 Sep 2026 16:00:59 +0000

Overview

A Telegram Mini App built with React needs a reliable way to prove its identity to users and your backend. This guide shows how to:

Accept an initData header from the Telegram client.
Validate the data structure and extract the embedded user ID.
Issue a signed JWT on your server after confirming the payload matches expectations.
Reject requests where the user ID doesn't match the authenticated session.

This pattern prevents spoofed requests and ensures only authorized mini apps can interact with your backend.

Architecture

┌─────────────┐      ┌──────────────────┐      ┌─────────────┐
│   React     │◄────►│  Telegram Client  │◄────►│  Your API    │
│  Mini App   │      │  (initiData)      │      │  (PHP/Node)  │
└─────────────┘      └──────────────────┘      └─────────────┘
       │                      │                        \
       ▼                      ▼                         \
   initData header        JWT issuance                Token verification

Step 1 – Backend: Receive initData and Issue JWT

On your PHP side (e.g., a Laravel controller or plain script), listen for the Telegram webhook or direct API call. Extract initData, validate it, and return a JWT if everything looks good.

<?php
// Minimal PHP handler (can be adapted to Laravel)
require 'vendor/autoload.php';

use Illuminate\HttpRequest;
use Illuminate\Support\Facades\Route;

// Secret used to sign/verify JWTs
const JWT_SECRET = env('JWT_SECRET', 'your-secret-change-me');

// Expected initData format:
// { "userId": "abc123", "token": "xyz789" }
// The userId comes from your database lookup.

function handleInitData(Request $request): Response {
    // 1. Read initData from the header
    $initData = $request->header('X-InitData');
    if (!$initData) {
        return response()->json(['error' => 'Missing initData'], 400);
    }

    // 2. Decode and validate the payload
    $payload = json_decode($initData, true);
    if (!is_array($payload) || !isset($payload['userId']) && !isset($payload['token'])) {
        return response()->json(['error' => 'Invalid initData'], 400);
    }

    // 3. Verify the user ID exists in your system (prevents spoofing)
    $user = User::find($payload['userId']);
    if (!$user) {
        // Log the attempt but do NOT reveal whether the user exists
        error_log("Unauthorized initData attempt: user_id=\{payload['userId']}");
        return response()->json(['error' => 'Unauthorized'], 401);
    }

    // 4. Issue a fresh JWT for subsequent calls
    $jwt = (\.jsonwebtoken\JWT::encode(
        ['sub' => $user->id, 'exp' => time() + 3600]
    ), JWT_SECRET);

    // Return the JWT so the frontend can store it
    return response()->json(['jwt' => $jwt]);
}

Key security decisions:

The userId inside initData is checked against your database before trusting anything else.
Only after a successful lookup do you issue a new JWT. This ties the initial auth to a fresh token each time.
Failed lookups return 401 Unauthorized without revealing which field was missing.

Step 2 – Frontend: Send initData from React

In your React component, construct the request with the initData header and include the JWT in the body (or as a query param depending on your flow).

import React, { useState } from 'react';
import axios from 'axios';

const TelegramMiniApp = () => {
  const [jwt, setJwt] = useState(null);

  const submitToTelegram = async () => {
    // Fetch the JWT from your backend first
    const res = await fetch('/api/init-data', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    if (!res.ok) throw new Error('Failed to obtain JWT');
    const { jwt } = await res.json();
    setJwt(jwt);

    // Now send the request with both initData and JWT
    try {
      const resp = await axios.post(
        'https://yourapp.com/api/notify',
        { action: 'submit_form' },
        {
          headers: {
            'Authorization': `Bearer ${jwt}`,
            'X-InitData': JSON.stringify({ /* optional extra fields */ }),
          },
        }
      );
      console.log('Form submitted:', resp.data);
    } catch (err) {
      console.error('Submission failed:', err);
    }
  };

  return (
    <div>
      <button onClick={submitToTelegram} disabled={!jwt || !jwt.startsWith('eyJ')}>
        Submit
      </button>
      {jwt && <p>Authenticated (JWT expires in {Math.floor((Date.now() + 3600 - Date.now()) / 1000)}s)</p>}
    </div>
  );
};

export default TelegramMiniApp;

Why two headers?

X-InitData: Contains the opaque userId and any additional context the client needs. It's validated server-side to prevent tampering.
Authorization: Bearer <jwt>: Verifies the request came from an authenticated session. The JWT itself is verified by your backend before reaching this point.

Step 3 – Server-Side Verification Flow

When your backend receives a POST from the mini app (e.g., /api/notify), follow this sequence:

Check the JWT signature using your secret (Laravel: \.jsonwebtoken\JWT::verify()).
Extract the userId from the decoded payload.
Look up the corresponding user in your database. If not found, reject with 401.
Proceed with the actual business logic (e.g., save form data, trigger actions).

<?php
require 'vendor/autoload.php';

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Laravel\Sanctum\JWT\RefreshToken;

// Simulated user model
class User {
    public function __construct(
        public int $id,
        public string $email,
        public ?string $realUserId = null
    ) {}
}

function processNotify(Request $request) {
    // 1. Verify JWT
    $jwt = $request->header('Authorization');
    if (!$jwt) {
        return response()->json(['error' => 'Missing JWT'], 401);
    }
    try {
        $decoded = \\JsonWebToken::decode($jwt, JWT_SECRET);
        $expectedUserId = $decoded->get('sub');
    } catch (\\Exception $e) {
        return response()->json(['error' => 'Invalid JWT'], 401);
    }

    // 2. Check that the user exists in our DB
    // In a real app, use Eloquent: User::where('id', $expectedUserId)->first();
    // For demo, we simulate:
    if ($expectedUserId === 'nonexistent-id') {
        return response()->json(['error' => 'Unauthorized'], 401);
    }

    // 3. Proceed with the actual work
    // ... save data, etc.

    return response()->json(['status' => 'ok']);
}

Step 4 – Preventing User ID Spoofing

The most common attack vector is a malicious client crafting initData with a fake userId. Our defense is layered:

Layer	Mechanism
Header validation	Server checks that `userId` appears in the `initData` payload.
Database lookup	After extracting `userId`, we verify it exists in our `users` table.
JWT binding	The JWT carries the canonical `sub` (user ID) and is verified independently.

If any layer fails, the request is rejected before any business logic runs.

Production Notes

Store the JWT securely (httpOnly cookies or secure storage) on the client side; never log it.
Rotate secrets regularly and keep them out of version control.
Rate-limit the /api/init-data endpoint to mitigate brute-force attempts.
Use HTTPS for all communication between the mini app and your backend.
Consider adding a CSRF-like guard for sensitive operations beyond just the initData exchange.

Build Interactive Telegram Inline Keyboards in PHP

Serhii — Tue, 22 Sep 2026 07:07:26 +0000

Telegram inline keyboards allow bots to attach interactive buttons directly to messages. When a user clicks an inline button, Telegram delivers a callback_query update to your webhook or polling worker instead of sending a standard text message. Designing a reliable inline keyboard workflow requires understanding callback query handling, message editing, and strict payload constraints.

In this tutorial, we will build a production-ready PHP handler for Telegram InlineKeyboardMarkup. We will cover constructing inline keypads, handling callback_query updates, invoking answerCallbackQuery to prevent UI hangs, and modifying messages in-place with editMessageText. We will also examine strategies to stay strictly under Telegram's 64-byte limit for callback_data payloads.

We will not cover high-level bot frameworks, database ORMs, or polling implementations. This guide relies strictly on native PHP cURL execution and explicit array structures.

The 64-Byte Callback Data Constraint

Every inline button with a callback_data property transmits a payload back to your server when pressed. Telegram imposes a strict upper limit of 64 bytes on the callback_data string. This is a byte-count limit, not a character-count limit. If you include multi-byte UTF-8 characters (such as localized text or emojis), the character capacity drops significantly.

Attempting to send JSON blobs or extended state models inside callback_data will cause API errors. For example, a JSON payload like {"action":"view_item","item_id":"987654321","category":"electronics"} is 63 characters long, but any added metadata or multi-byte string will break the request.

To manage state efficiently within 64 bytes, adopt compact encoding schemes:

Delimiter-separated short strings: Structure actions with short prefixes, such as act:id (e.g., v:101 for view item 101, e:101 for edit, d:101 for delete).
Bitwise or positional parameters: Pass multiple parameters as colon-separated or pipe-separated integers (e.g., p:14:2:1 representing page 14, filter 2, sort 1).
Server-side session keys: If the payload must carry complex filters or form state, store the data in Redis or a database against a short random hash (e.g., s:a1f8c9e2) generated via bin2hex(random_bytes(4)). Read the full state server-side when the callback arrives.

Delivering Messages with Inline Keyboards

An InlineKeyboardMarkup consists of an array of button rows, where each row is an array of InlineKeyboardButton objects. Below is a reusable PHP function that sends a message containing an inline keyboard using standard cURL execution.

<?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,
    ]);
}

The cURL helper verifies HTTP status codes, ensures JSON parsing succeeds, and explicitly checks for Telegram's ok: true field. Passing unvalidated requests to Telegram can fail silently or mask server errors.

Processing `callback_query` and `answerCallbackQuery`

When a user taps an inline button, Telegram sends an update object containing a callback_query dictionary. This payload includes a unique id for the query, the from user object, the original message where the button was attached, and the string passed in callback_data.

You must call the answerCallbackQuery API method for every incoming callback query. If you omit this call, the client interface displays a loading spinner on the button for up to 60 seconds, creating an unresponsive user experience. answerCallbackQuery allows you to stop the spinner, show a temporary toast notification, or present a modal alert dialog.

<?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);
}

Setting show_alert => true presents a full modal popup requiring explicit dismissal, while show_alert => false (the default) displays a brief banner at the top of the chat interface.

Editing Messages in Place with `editMessageText`

Instead of cluttering the chat history with new messages when options are selected, update the existing message text and reply markup using editMessageText. To modify a message originated by the bot, pass both chat_id and message_id along with the revised content.

<?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,
    ]);
}

Telegram's API returns a 400 Bad Request: message is not modified error if you attempt to call editMessageText with content and keypads identical to the message's current state. Always verify that state has changed before invoking this endpoint, or catch the exception gracefully.

Unified Webhook Action Handler

Below is a complete, single-file script demonstrating how to receive a webhook request, validate the incoming payload type, answer the callback query immediately, parse short parameters, and update the message UI.

<?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';

Production Edge Cases and Best Practices

Webhook Security: Validate the X-Telegram-Bot-Api-Secret-Token header sent by Telegram against your stored secret before parsing incoming payloads. Reject any request missing the correct token with an HTTP 403 status.
Idempotency: Webhook delivery guarantees at-least-once delivery. High network latency can lead Telegram to retry sending an update. Record processed update_id values in a fast key-value store like Redis with a 24-hour expiration window. Ignore updates whose IDs have already been stored.
HTML Sanitization: When using 'parse_mode' => 'HTML', always wrap dynamic variable values (such as names, user input, or system identifiers) inside htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'). Malformed tags will cause Telegram's API to reject the message edit with a 400 Bad Request: can't parse entities error.
Expired Messages: If an inline message is very old or deleted by the user, editMessageText will fail. Wrap menu state updates in try/catch blocks and handle error responses gracefully.

For production deployments requiring complex custom user interfaces, workflows, or Mini Apps, BotCreator ships tailored Telegram bots and integrations. You can also refer to technical guides on the Telegram Bot API to learn more about backend integration patterns.

Route Website Form Submissions to Telegram Managers in PHP

Serhii — Mon, 21 Sep 2026 16:02:16 +0000

This tutorial demonstrates how to integrate a website contact form with Telegram, allowing form submissions to be routed as messages to a group of managers. We will cover processing form data, generating a unique lead identifier, storing this identifier, and sending an interactive message to Telegram with an inline button for managers to claim the lead. We will not be covering front-end form validation or advanced database schema design, focusing solely on the backend PHP logic for Telegram integration.

1. Setting up the Environment and Telegram Bot

Before we dive into the PHP code, ensure you have a Telegram bot token and a chat ID for the group where managers will receive lead notifications. You can obtain a bot token from BotFather. To get the chat ID, add your bot to a group, send a message, and then visit https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates to find the chat.id.

For security, store your bot token and chat ID as environment variables or in a configuration file, not directly in your code. We'll use getenv() for this example.

// config.php or environment variables
// TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
// TELEGRAM_MANAGER_CHAT_ID=-123456789

2. Processing Form Submissions

Let's assume you have an HTML form on your website that submits data via POST to a PHP script. For this example, we'll simulate a form submission with name and email fields.

<?php

// Ensure this script is only accessible via POST requests
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405); // Method Not Allowed
    echo 'Only POST requests are allowed.';
    exit;
}

// Load environment variables (e.g., from a .env file or server configuration)
// For simplicity, we'll assume they are already loaded or set in the server environment.
$telegramBotToken = getenv('TELEGRAM_BOT_TOKEN');
$telegramManagerChatId = getenv('TELEGRAM_MANAGER_CHAT_ID');

if (!$telegramBotToken || !$telegramManagerChatId) {
    error_log('Missing Telegram bot token or manager chat ID.');
    http_response_code(500); // Internal Server Error
    echo 'Configuration error.';
    exit;
}

// Sanitize and validate input data
$name = filter_input(INPUT_POST, 'name', FILTER_SANITIZE_STRING);
$email = filter_input(INPUT_POST, 'email', FILTER_VALIDATE_EMAIL);
$message = filter_input(INPUT_POST, 'message', FILTER_SANITIZE_STRING);

if (!$name || !$email) {
    http_response_code(400); // Bad Request
    echo 'Invalid input data.';
    exit;
}

// Generate a unique lead ID
// Using bin2hex(random_bytes(7)) generates a 14-character hexadecimal string,
// which is sufficiently unique for most applications and fits within typical database column sizes.
$leadId = bin2hex(random_bytes(7));

// Store lead data (e.g., in a database)
// For this example, we'll just simulate storage. In a real application,
// you would insert this into a 'leads' table with columns like id, name, email, message, created_at, status.
$dbConnection = new PDO('sqlite::memory:'); // Example: using SQLite in memory for demonstration
$dbConnection->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$dbConnection->exec("CREATE TABLE IF NOT EXISTS leads (id TEXT PRIMARY KEY, name TEXT, email TEXT, message TEXT, created_at DATETIME)");

try {
    $stmt = $dbConnection->prepare("INSERT INTO leads (id, name, email, message, created_at) VALUES (:id, :name, :email, :message, DATETIME('now'))");
    $stmt->execute([
        ':id' => $leadId,
        ':name' => $name,
        ':email' => $email,
        ':message' => $message
    ]);
} catch (PDOException $e) {
    error_log('Database error: ' . $e->getMessage());
    http_response_code(500);
    echo 'Failed to store lead.';
    exit;
}

// Prepare message for Telegram
$telegramMessage = "<b>New Lead!</b>\n\n";
$telegramMessage .= "<b>ID:</b> " . htmlspecialchars($leadId) . "\n";
$telegramMessage .= "<b>Name:</b> " . htmlspecialchars($name) . "\n";
$telegramMessage .= "<b>Email:</b> " . htmlspecialchars($email) . "\n";
$telegramMessage .= "<b>Message:</b> " . htmlspecialchars($message) . "\n";

// Create an inline keyboard button for managers to 'take' the lead
// The callback_data must be a string and its length must not exceed 64 bytes.
// We'll use a simple format: 'take:LEAD_ID'
$callbackData = 'take:' . $leadId;
if (strlen($callbackData) > 64) {
    error_log('Callback data exceeds 64 bytes: ' . $callbackData);
    // Handle this edge case, e.g., by logging and not sending the button
    $inlineKeyboard = [];
} else {
    $inlineKeyboard = [
        'inline_keyboard' => [
            [
                ['text' => 'Take Lead', 'callback_data' => $callbackData]
            ]
        ]
    ];
}

// Send message to Telegram
$telegramApiUrl = "https://api.telegram.org/bot{$telegramBotToken}/sendMessage";

$postFields = [
    'chat_id' => $telegramManagerChatId,
    'text' => $telegramMessage,
    'parse_mode' => 'HTML',
    'reply_markup' => json_encode($inlineKeyboard)
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $telegramApiUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);

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

if ($response === false) {
    error_log('cURL error: ' . $curlError);
    http_response_code(500);
    echo 'Failed to send message to Telegram (cURL error).';
    exit;
}

$responseData = json_decode($response, true);

if ($httpCode !== 200 || !isset($responseData['ok']) || $responseData['ok'] !== true) {
    error_log('Telegram API error: HTTP ' . $httpCode . ' - ' . ($responseData['description'] ?? 'Unknown error'));
    http_response_code(500);
    echo 'Failed to send message to Telegram (API error).';
    exit;
}

http_response_code(200);
echo 'Lead submitted successfully and sent to Telegram.';

?>

3. Handling the Callback Query (Manager's Action)

When a manager clicks the 'Take Lead' button, Telegram sends a callback_query update to your bot's webhook. You need a separate script (or a webhook handler that routes requests) to process this. This script will receive the callback_data we defined (take:LEAD_ID).

<?php

// This script assumes it's configured as your bot's webhook URL.
// It should only accept POST requests from Telegram.

$telegramBotToken = getenv('TELEGRAM_BOT_TOKEN');

if (!$telegramBotToken) {
    error_log('Missing Telegram bot token for webhook handler.');
    http_response_code(500);
    exit;
}

// Read the incoming Telegram update
$input = file_get_contents('php://input');
$update = json_decode($input, true);

// Log the incoming update for debugging (optional)
// file_put_contents('telegram_updates.log', date('Y-m-d H:i:s') . "\n" . $input . "\n\n", FILE_APPEND);

if (json_last_error() !== JSON_ERROR_NONE) {
    error_log('Invalid JSON received: ' . json_last_error_msg());
    http_response_code(400); // Bad Request
    exit;
}

// Check if it's a callback query
if (isset($update['callback_query'])) {
    $callbackQuery = $update['callback_query'];
    $callbackData = $callbackQuery['data'];
    $queryId = $callbackQuery['id'];
    $chatId = $callbackQuery['message']['chat']['id'];
    $messageId = $callbackQuery['message']['message_id'];
    $fromUser = $callbackQuery['from'];
    $managerName = htmlspecialchars($fromUser['first_name'] . (isset($fromUser['last_name']) ? ' ' . $fromUser['last_name'] : ''));

    // Check if the callback data starts with 'take:'
    if (strpos($callbackData, 'take:') === 0) {
        $leadId = substr($callbackData, 5);

        // In a real application, you would query your database here
        // to check the lead's status and assign it to the manager.
        // For demonstration, we'll simulate this.

        $dbConnection = new PDO('sqlite::memory:'); // Re-initialize for this script, or use a shared connection
        $dbConnection->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
        $dbConnection->exec("CREATE TABLE IF NOT EXISTS leads (id TEXT PRIMARY KEY, name TEXT, email TEXT, message TEXT, created_at DATETIME, assigned_to TEXT DEFAULT NULL)");

        // Attempt to retrieve the lead and assign it
        try {
            $stmt = $dbConnection->prepare("SELECT assigned_to FROM leads WHERE id = :id");
            $stmt->execute([':id' => $leadId]);
            $lead = $stmt->fetch(PDO::FETCH_ASSOC);

            $responseMessage = '';
            if ($lead) {
                if ($lead['assigned_to'] === null) {
                    // Assign the lead to the manager
                    $updateStmt = $dbConnection->prepare("UPDATE leads SET assigned_to = :managerName WHERE id = :id");
                    $updateStmt->execute([':managerName' => $managerName, ':id' => $leadId]);
                    $responseMessage = "Lead {$leadId} assigned to {$managerName}.";

                    // Edit the original message to reflect the assignment
                    $originalText = $callbackQuery['message']['text'];
                    $newText = $originalText . "\n\n<i>Assigned to: {$managerName}</i>";
                    $this->editTelegramMessage($telegramBotToken, $chatId, $messageId, $newText, true); // Remove inline keyboard

                } else {
                    $responseMessage = "Lead {$leadId} is already assigned to {$lead['assigned_to']}.";
                }
            } else {
                $responseMessage = "Lead {$leadId} not found.";
            }

            // Answer the callback query to remove the loading state from the button
            $this->answerCallbackQuery($telegramBotToken, $queryId, $responseMessage);

        } catch (PDOException $e) {
            error_log('Database error during lead assignment: ' . $e->getMessage());
            $this->answerCallbackQuery($telegramBotToken, $queryId, 'Error processing lead assignment.');
        }
    }
}

// Always respond with 200 OK to Telegram to acknowledge receipt of the update
http_response_code(200);

class TelegramApi {
    private function callApi(string $method, array $params = []): array
    {
        $telegramBotToken = getenv('TELEGRAM_BOT_TOKEN');
        if (!$telegramBotToken) {
            error_log('Telegram bot token not set.');
            return ['ok' => false, 'description' => 'Bot token missing'];
        }

        $url = "https://api.telegram.org/bot{$telegramBotToken}/{$method}";
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);

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

        if ($response === false) {
            error_log("cURL error for {$method}: " . $curlError);
            return ['ok' => false, 'description' => 'cURL error: ' . $curlError];
        }

        $responseData = json_decode($response, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            error_log("JSON decode error for {$method}: " . json_last_error_msg() . " Response: " . $response);
            return ['ok' => false, 'description' => 'Invalid JSON response'];
        }

        if ($httpCode !== 200 || !isset($responseData['ok']) || $responseData['ok'] !== true) {
            error_log("Telegram API error for {$method}: HTTP {$httpCode} - " . ($responseData['description'] ?? 'Unknown error') . " Response: " . $response);
            return ['ok' => false, 'description' => $responseData['description'] ?? 'API error'];
        }

        return $responseData;
    }

    public function answerCallbackQuery(string $botToken, string $callbackQueryId, string $text, bool $showAlert = false):
    void {
        $params = [
            'callback_query_id' => $callbackQueryId,
            'text' => $text,
            'show_alert' => $showAlert ? 'true' : 'false'
        ];
        $this->callApi('answerCallbackQuery', $params);
    }

    public function editTelegramMessage(string $botToken, int $chatId, int $messageId, string $newText, bool $removeKeyboard = false):
    void {
        $params = [
            'chat_id' => $chatId,
            'message_id' => $messageId,
            'text' => $newText,
            'parse_mode' => 'HTML'
        ];
        if ($removeKeyboard) {
            $params['reply_markup'] = json_encode(['inline_keyboard' => []]); // Empty keyboard to remove it
        }
        $this->callApi('editMessageText', $params);
    }
}

// Instantiate the class and call the method
$this = new TelegramApi();

?>

4. Production Notes and Considerations

Security: Always validate and sanitize all user inputs. For webhooks, implement a secret_token to verify that incoming requests are from Telegram. This is crucial to prevent unauthorized access to your webhook endpoint. You can set a secret_token when setting your webhook via setWebhook API method and then verify the X-Telegram-Bot-Api-Secret-Token header in your PHP script.
Database: The SQLite in-memory database used here is for demonstration only. In a production environment, you would use a persistent database like MySQL, PostgreSQL, or a file-based SQLite database, ensuring proper connection management and error handling.
Idempotency: For webhook handlers, it's good practice to ensure idempotency. Telegram sends update_id with each update. You can store the last processed update_id in your database or a cache (like Redis) and ignore updates with an update_id less than or equal to the last processed one. This prevents duplicate processing if Telegram retries sending an update.
Error Handling and Logging: Implement robust error handling and logging. Use error_log() to write errors to your server's error log, and consider a more sophisticated logging solution for production. Always return appropriate HTTP status codes.
Asynchronous Processing: For heavy processing or external API calls, consider using a message queue (e.g., RabbitMQ, Redis Queue, AWS SQS) to process Telegram updates asynchronously. This prevents your webhook from timing out and improves responsiveness.
callback_data Length: The 64-byte limit for callback_data is strict. If your lead IDs or other data exceed this, you might need to store a mapping in your database (e.g., short_id -> long_id) and send only the short_id in the callback_data.
Telegram API Rate Limits: Be mindful of Telegram Bot API rate limits. If you're sending many messages or making many API calls, you might hit limits. Implement retry logic with exponential backoff if you encounter 429 Too Many Requests errors.
User Interface: When a manager takes a lead, editing the original message to show who took it (and removing the inline button) provides clear feedback and prevents multiple managers from trying to claim the same lead simultaneously.

This setup provides a solid foundation for integrating website forms with Telegram for lead management. By following these guidelines, you can build a reliable and secure system.

BotCreator — studio that ships Telegram bots / Mini Apps.

Handle Telegram Bot API Rate Limits and 429 Errors in PHP

Serhii — Mon, 21 Sep 2026 07:00:45 +0000

When scaling a Telegram bot, you will eventually encounter rate limits. Telegram enforces strict limits on how fast your bot can send messages. If you exceed these limits, the Bot API returns an HTTP 429 Too Many Requests status code.

This tutorial demonstrates how to handle HTTP 429 errors in PHP, extract the retry delay, and structure an outgoing message queue to prevent rate-limiting bottlenecks during broadcasts. We do not claim to build a fully distributed Redis-backed queue system here, but rather provide the core reference implementation for handling limits and retries.

Understanding Telegram's Rate Limits

Telegram enforces several limits on outgoing messages:

Global limit: Max 30 messages per second across all chats.
Single chat limit: Max 20 messages per minute (approx. 1 message every 3 seconds) to a specific user, group, or channel.
Broadcast limit: Max 30 messages per second when sending to multiple users.

When you exceed these thresholds, the API returns a JSON response containing "ok": false, "error_code": 429, and a parameters object with a retry_after integer specifying the number of seconds you must wait before retrying.

1. Implementing a Rate-Limit Aware HTTP Client

This PHP class wraps cURL to send requests to the Telegram Bot API. It checks the HTTP status code, validates the JSON response, and throws a custom exception containing the retry_after value when a 429 error occurs.

<?php

declare(strict_types=1);

class TelegramRateLimitException extends Exception 
{
    private int $retryAfter;

    public function __construct(int $retryAfter, string $message = "Rate limit exceeded") 
    {
        parent::__construct($message, 429);
        $this->retryAfter = $retryAfter;
    }

    public function getRetryAfter(): int 
    {
        return $this->retryAfter;
    }
}

class TelegramClient 
{
    private string $token;

    public function __construct()
    {
        $this->token = (string) getenv('TELEGRAM_BOT_TOKEN');
        if ($this->token === '') {
            throw new RuntimeException('TELEGRAM_BOT_TOKEN environment variable is not set.');
        }
    }

    public function sendRequest(string $method, array $payload): array
    {
        $url = "https://api.telegram.org/bot{$this->token}/{$method}";
        $jsonPayload = json_encode($payload);

        if ($jsonPayload === false) {
            throw new InvalidArgumentException('Failed to encode payload to JSON: ' . json_last_error_msg());
        }

        $ch = curl_init($url);
        if ($ch === false) {
            throw new RuntimeException('Failed to initialize cURL.');
        }

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

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

        if ($response === false) {
            throw new RuntimeException("cURL request failed: {$curlError}");
        }

        $data = json_decode($response, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new RuntimeException('Failed to parse Telegram API response as JSON.');
        }

        if ($httpCode === 429) {
            $retryAfter = $data['parameters']['retry_after'] ?? 1;
            throw new TelegramRateLimitException((int) $retryAfter);
        }

        if (isset($data['ok']) && $data['ok'] === false) {
            $description = $data['description'] ?? 'Unknown error';
            throw new RuntimeException("Telegram API Error: {$description} (Code: {$httpCode})");
        }

        return $data;
    }
}

2. Structuring an Outgoing Message Queue

To prevent hitting the 20 messages per minute limit for a single chat, you should avoid sending messages synchronously in response to webhooks or user actions. Instead, write messages to a database queue and process them with a background worker.

Below is a schema and a simplified worker loop that respects both the per-chat limit and the global 30 messages/second limit.

CREATE TABLE telegram_message_queue (
    id INT AUTO_INCREMENT PRIMARY KEY,
    chat_id BIGINT NOT NULL,
    payload JSON NOT NULL,
    status VARCHAR(20) DEFAULT 'pending', -- pending, sent, failed, rate_limited
    retry_after_time DATETIME NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_status_retry (status, retry_after_time),
    INDEX idx_chat_status (chat_id, status)
);

Here is the PHP worker script that processes this queue. It tracks the last sent time per chat_id to enforce the 3-second delay (20 messages/minute) and handles TelegramRateLimitException by pausing the queue or rescheduling the message.

<?php

declare(strict_types=1);

// Assuming PDO connection $pdo and TelegramClient $client are initialized

$client = new TelegramClient();
$lastSentToChat = []; // Tracks last send timestamp per chat_id

while (true) {
    // Fetch pending messages that are not locked by a retry delay
    $stmt = $pdo->prepare("
        SELECT id, chat_id, payload 
        FROM telegram_message_queue 
        WHERE status = 'pending' 
          AND (retry_after_time IS NULL OR retry_after_time <= NOW())
        ORDER BY id ASC 
        LIMIT 30
    ");
    $stmt->execute();
    $messages = $stmt->fetchAll(PDO::FETCH_ASSOC);

    if (empty($messages)) {
        sleep(1); // No messages, idle
        continue;
    }

    $sentThisBatch = 0;

    foreach ($messages as $msg) {
        $chatId = (int) $msg['chat_id'];
        $payload = json_decode($msg['payload'], true);
        $now = microtime(true);

        // Enforce the 3-second delay per chat to prevent hitting the 20 msg/min limit
        if (isset($lastSentToChat[$chatId]) && ($now - $lastSentToChat[$chatId]) < 3.0) {
            continue; // Skip this message for this iteration to let other chats process
        }

        try {
            $client->sendRequest('sendMessage', $payload);

            // Update status to sent
            $update = $pdo->prepare("UPDATE telegram_message_queue SET status = 'sent' WHERE id = ?");
            $update->execute([$msg['id']]);

            $lastSentToChat[$chatId] = microtime(true);
            $sentThisBatch++;

            // Enforce global limit: max 30 messages per second
            if ($sentThisBatch >= 30) {
                sleep(1);
                $sentThisBatch = 0;
            }
        } catch (TelegramRateLimitException $e) {
            $retryAfter = $e->getRetryAfter();

            // Reschedule this message and set status back to pending with a delay
            $delayUntil = (new DateTime())->modify("+{$retryAfter} seconds")->format('Y-m-d H:i:s');
            $update = $pdo->prepare("
                UPDATE telegram_message_queue 
                SET status = 'pending', retry_after_time = ? 
                WHERE id = ?
            ");
            $update->execute([$delayUntil, $msg['id']]);

            // Pause the worker for the duration of the rate limit to avoid spamming the API
            sleep($retryAfter);
            break; // Break the foreach loop to fetch fresh data after the sleep
        } catch (Exception $e) {
            // Handle permanent failures (e.g., user blocked bot)
            $update = $pdo->prepare("UPDATE telegram_message_queue SET status = 'failed' WHERE id = ?");
            $update->execute([$msg['id']]);
        }
    }

    // Clean up memory for inactive chats
    if (count($lastSentToChat) > 1000) {
        $lastSentToChat = array_slice($lastSentToChat, -500, null, true);
    }

    usleep(100000); // 100ms sleep between batches
}

Production Notes

Grouping Messages: If your bot needs to send multiple updates to a single chat (e.g., a notification with text and several images), do not send them as separate messages. Group them using the sendMediaGroup method or concatenate the text into a single sendMessage payload. This reduces your request volume and prevents hitting the 20 msg/min limit.
Webhook Secret Token: When processing incoming updates via webhooks, always verify the X-Telegram-Bot-Api-Secret-Token header to ensure the request originates from Telegram before processing or queuing any actions.
Database Cleanup: In production, clean up or archive rows in telegram_message_queue with status = 'sent' or status = 'failed' regularly to keep index lookups fast.

For more details on the underlying API limits and webhook specifications, refer to the official documentation at https://botservice.biz/telegram-bot-api.

BotCreator — studio that ships Telegram bots / Mini Apps.

Securely Authenticate Users with the Telegram Login Widget in PHP and Yii2

Serhii — Sun, 20 Sep 2026 16:00:32 +0000

Integrating the Telegram Login Widget provides a frictionless authentication flow for web applications. However, accepting raw authentication parameters from the client side without strict cryptographic verification exposes your application to identity spoofing.

This guide demonstrates how to build a secure backend validator in PHP to verify the Telegram Login Widget payload using HMAC-SHA-256, enforce strict expiration checks on the authentication timestamp, and map the validated Telegram ID to a user record in the Yii2 framework. We do not cover the frontend HTML widget rendering or session storage configuration.

The Telegram Verification Algorithm

When a user authenticates via the Telegram Login Widget, your redirect URL or callback receives a set of query parameters (such as id, first_name, username, auth_date, and hash). To verify this payload:

Sort all received parameters alphabetically by key, excluding the hash parameter.
Format these parameters into a string of key=value pairs, separated by a newline character (\n).
Derive a secret key by calculating the SHA-256 hash of your Telegram Bot Token in binary format.
Compute the HMAC-SHA-256 signature of the formatted parameter string using the derived secret key.
Compare the computed signature against the received hash parameter using a timing-attack-resistant comparison function.

Step 1: Implementing the PHP Validator Class

This standalone class handles the cryptographic verification of the incoming payload. It uses hash_equals to mitigate timing attacks and checks the age of the auth_date parameter to prevent replay attacks.

<?php

namespace app\components;

use InvalidArgumentException;

class TelegramAuthValidator
{
    private string $botToken;

    public function __construct(string $botToken)
    {
        if (empty($botToken)) {
            throw new InvalidArgumentException("Telegram bot token cannot be empty.");
        }
        $this->botToken = $botToken;
    }

    /**
     * Validates the Telegram authentication payload.
     * 
     * @param array $params The query parameters received from Telegram.
     * @param int $maxAge Maximum allowed age of the authentication in seconds (default: 24 hours).
     * @return bool True if the payload is valid and fresh, false otherwise.
     */
    public function validate(array $params, int $maxAge = 86400): bool
    {
        if (!isset($params['hash']) || !isset($params['auth_date'])) {
            return false;
        }

        // Prevent replay attacks by checking the age of the authentication
        $authDate = (int)$params['auth_date'];
        if ((time() - $authDate) > $maxAge) {
            return false;
        }

        $receivedHash = $params['hash'];
        unset($params['hash']);

        // Sort parameters alphabetically by key
        ksort($params);

        // Build the data-check-string
        $dataCheckArr = [];
        foreach ($params as $key => $value) {
            $dataCheckArr[] = $key . '=' . $value;
        }
        $dataCheckString = implode("\n", $dataCheckArr);

        // Derive the secret key from the bot token
        $secretKey = hash('sha256', $this->botToken, true);

        // Calculate the HMAC-SHA-256 signature
        $calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey);

        // Compare hashes securely
        return hash_equals($calculatedHash, $receivedHash);
    }
}

Step 2: Integrating with Yii2 Controller and Database Mapping

To map the authenticated Telegram user to your local database, you must first ensure your user table contains a column for the Telegram ID.

Run a migration to add the column and a unique index:

# Create migration
./yii migrate/create add_telegram_id_to_user_table

Update the migration file to include the column:

<?php

use yii\db\Migration;

class m231024_120000_add_telegram_id_to_user_table extends Migration
{
    public function safeUp()
    {
        $this->addColumn('{{%user}}', 'telegram_id', $this->string(64)->unique()->null());
        $this->createIndex('idx-user-telegram_id', '{{%user}}', 'telegram_id', true);
    }

    public function safeDown()
    {
        $this->dropIndex('idx-user-telegram_id', '{{%user}}');
        $this->dropColumn('{{%user}}', 'telegram_id');
    }
}

Next, implement the controller action that handles the callback from the Telegram Login Widget. This action validates the payload, checks if a user with the given telegram_id exists, registers them if they do not, and logs them into the Yii2 application.

<?php

namespace app\controllers;

use Yii;
\use yii\web\Controller;
\use yii\web\BadRequestHttpException;
\use yii\web\ServerErrorHttpException;
\use app\models\User;
\use app\components\TelegramAuthValidator;

class AuthController extends Controller
{
    /**
     * Handles the redirect callback from the Telegram Login Widget.
     */
    public function actionTelegramCallback()
    {
        $request = Yii::$app->request;
        $params = $request->get();

        // Retrieve the bot token securely from environment variables or application parameters
        $botToken = Yii::$app->params['telegram.bot_token'] ?? getenv('TELEGRAM_BOT_TOKEN');
        if (empty($botToken)) {
            throw new ServerErrorHttpException("Telegram bot configuration is missing.");
        }

        $validator = new TelegramAuthValidator($botToken);

        // Validate signature and enforce a 12-hour expiration window
        if (!$validator->validate($params, 43200)) {
            throw new BadRequestHttpException("Invalid or expired Telegram authentication payload.");
        }

        $telegramId = (string)$params['id'];

        // Attempt to find an existing user mapped to this Telegram ID
        $user = User::findOne(['telegram_id' => $telegramId]);

        if (!$user) {
            // If the user is already logged in, link their current account
            if (!Yii::$app->user->isGuest) {
                $user = Yii::$app->user->identity;
                $user->telegram_id = $telegramId;
                if (!$user->save(true, ['telegram_id'])) {
                    throw new ServerErrorHttpException("Failed to link Telegram account.");
                }
            } else {
                // Otherwise, register a new user account
                $user = new User();
                $user->telegram_id = $telegramId;
                $user->username = $params['username'] ?? 'tg_' . $telegramId;
                // Generate a random password and email placeholder if required by your schema
                $user->password_hash = Yii::$app->security->generatePasswordHash(random_bytes(32));

                if (!$user->save()) {
                    Yii::error("Failed to register Telegram user: " . json_encode($user->getErrors()), __METHOD__);
                    throw new ServerErrorHttpException("Failed to register user account.");
                }
            }
        }

        // Log the user in
        Yii::$app->user->login($user, 3600 * 24 * 30); // 30-day session

        return $this->goBack();
    }
}

Production Considerations

Strict Expiration (auth_date): Always enforce a reasonable expiration window (e.g., 1 to 24 hours). If you do not verify auth_date, an attacker who intercepts a valid query string can replay the login request indefinitely.
Database Constraints: Ensure the telegram_id column has a unique constraint at the database level. This prevents race conditions where two concurrent requests might attempt to register the same Telegram ID to different local accounts.
Data Sanitization: When saving the username or first_name returned by Telegram, sanitize the input to prevent XSS if you display these values on your website.

For developers building complex integrations, refer to the official Telegram documentation at https://botservice.biz/telegram-bot-api for details on managing user sessions and bot interactions.

Need assistance deploying production-ready Telegram integrations? Contact BotCreator — studio that ships Telegram bots / Mini Apps.

Build a Resilient Telegram Bot Service Layer in Yii2

Serhii — Sun, 20 Sep 2026 07:01:02 +0000

When building production-grade Telegram bots in Yii2, developers often make the mistake of writing ad-hoc cURL requests inside controllers or console commands. This approach leads to duplicated code, poor error visibility, and fragile integrations that break under network latency or API rate limits.

In this tutorial, we will build a robust, production-ready service layer for interacting with the Telegram Bot API within a Yii2 application. We will configure this service using Yii2's Dependency Injection (DI) container, store credentials securely in local configuration files, handle network failures, log API errors properly, and implement retry logic for HTTP 429 (Too Many Requests) responses.

We do not claim this is a complete framework wrapper or a replacement for complex SDKs. Instead, it is a clean, maintainable architectural pattern designed to replace ad-hoc HTTP calls with a resilient service component.

Secure Configuration with params-local.php

Hardcoding API credentials in your codebase is a major security risk and violates the principles of twelve-factor app design. In Yii2, the standard way to manage environment-specific configurations is through the params-local.php file, which should be added to your .gitignore file to prevent it from being committed to your version control system.

First, define your Telegram bot token in config/params-local.php:

<?php
// config/params-local.php

return [
    'telegram.botToken' => '123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ',
];

Next, configure Yii2's Dependency Injection (DI) container in your main application configuration file (config/web.php for web applications, and config/console.php for console commands). This ensures that whenever your application requests an instance of our TelegramClient, the DI container automatically instantiates it with the correct token from your parameters.

<?php
// config/web.php

$params = require __DIR__ . '/params.php';
if (file_exists(__DIR__ . '/params-local.php')) {
    $params = yii\helpers\ArrayHelper::merge($params, require __DIR__ . '/params-local.php');
}

$config = [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    // ... other configurations ...
    'container' => [
        'definitions' => [
            app\components\TelegramClient::class => [
                'class' => app\components\TelegramClient::class,
                'botToken' => $params['telegram.botToken'] ?? null,
                'maxRetries' => 3,
                'timeout' => 10,
            ],
        ],
    ],
    'params' => $params,
];

return $config;

Implementing the TelegramClient Component

The TelegramClient class must be resilient. Network timeouts, DNS resolution failures, and rate limits are common when communicating with external APIs. Our component will use PHP's cURL extension to execute requests, inspect HTTP status codes, validate JSON payloads, and handle HTTP 429 rate limits by parsing the Retry-After header and retrying the request after the specified delay.

Create the file components/TelegramClient.php:

<?php

namespace app\components;

use Yii;
use yii\base\BaseObject;
use yii\base\InvalidConfigException;

class TelegramClient extends BaseObject

{
    public ?string $botToken = null;
    public int $maxRetries = 3;
    public int $timeout = 10;

    public function init()
    {
        parent::init();
        if (empty($this->botToken)) {
            throw new InvalidConfigException('The "botToken" property must be configured.');
        }
    }

    /**
     * Sends a request to the Telegram Bot API.
     *
     * @param string $method The API method (e.g., "sendMessage")
     * @param array $params The parameters to send in the JSON body
     * @return array The parsed API response
     * @throws \RuntimeException If the request fails after maximum retries
     */
    public function sendRequest(string $method, array $params = []): array
    {
        $url = "https://api.telegram.org/bot{$this->botToken}/{$method}";
        $attempt = 0;

        while ($attempt < $this->maxRetries) {
            $attempt++;
            $ch = curl_init();

            curl_setopt_array($ch, [
                CURLOPT_URL => $url,
                CURLOPT_POST => true,
                CURLOPT_POSTFIELDS => json_encode($params),
                CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_TIMEOUT => $this->timeout,
                CURLOPT_HEADER => true, // Required to parse response headers for Retry-After
            ]);

            $response = curl_exec($ch);
            $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
            $curlError = curl_error($ch);
            curl_close($ch);

            if ($response === false) {
                Yii::error("Telegram API cURL error: {$curlError}. Attempt {$attempt}/{$this->maxRetries}", __METHOD__);
                if ($attempt >= $this->maxRetries) {
                    throw new \RuntimeException("Telegram API connection failed: {$curlError}");
                }
                usleep(500000 * $attempt); // Exponential backoff before retry
                continue;
            }

            $headersStr = substr($response, 0, $headerSize);
            $bodyStr = substr($response, $headerSize);

            if ($httpCode === 429) {
                $retryAfter = $this->parseRetryAfter($headersStr);
                Yii::warning("Telegram API rate limited (429). Retrying after {$retryAfter} seconds. Attempt {$attempt}/{$this->maxRetries}", __METHOD__);
                sleep($retryAfter);
                continue;
            }

            $data = json_decode($bodyStr, true);
            if (json_last_error() !== JSON_ERROR_NONE) {
                Yii::error("Failed to parse Telegram API response JSON: " . json_last_error_msg() . " | Raw body: {$bodyStr}", __METHOD__);
                throw new \RuntimeException("Invalid JSON response from Telegram API");
            }

            if ($httpCode !== 200 || !($data['ok'] ?? false)) {
                $description = $data['description'] ?? 'Unknown error';
                $errorCode = $data['error_code'] ?? $httpCode;
                Yii::error("Telegram API error response: [{$errorCode}] {$description}", __METHOD__);
                return $data;
            }

            return $data;
        }

        throw new \RuntimeException("Telegram API request failed after {$this->maxRetries} attempts.");
    }

    /**
     * Parses the Retry-After header from the response headers.
     */
    private function parseRetryAfter(string $headers): int
    {
        if (preg_match('/Retry-After:\s*(\d+)/i', $headers, $matches)) {
            return (int)$matches[1];
        }
        return 2; // Default fallback delay in seconds
    }
}

Injecting and Using the Service in a Controller

With our DI configuration in place, we can inject the TelegramClient directly into our controllers or console commands via constructor injection. This keeps our controllers clean, testable, and decoupled from the underlying HTTP client implementation.

When sending messages to Telegram using parse_mode = 'HTML', a common source of silent failures is unescaped HTML entities. Characters like <, >, and & will cause the Telegram API to reject the message with a 400 Bad Request error. We must use htmlspecialchars to sanitize our dynamic inputs before sending them.

Here is an example controller demonstrating constructor injection and safe message formatting:

<?php

namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\Response;
use app\components\TelegramClient;

class AlertController extends Controller
{
    private TelegramClient $telegram;

    // Yii2 DI container automatically resolves and injects the TelegramClient dependency
    public function __construct($id, $module, TelegramClient $telegram, $config = [])
    {
        $this->telegram = $telegram;
        parent::__construct($id, $module, $config);
    }

    public function actionSend(): Response
    {
        $this->response->format = Response::FORMAT_JSON;

        $chatId = Yii::$app->request->post('chat_id');
        $rawMessage = Yii::$app->request->post('message', '');

        if (empty($chatId)) {
            return [
                'success' => false,
                'error' => 'Missing chat_id parameter.',
            ];
        }

        // Safely escape HTML entities to prevent Telegram API parsing errors
        $safeMessage = htmlspecialchars($rawMessage, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
        $formattedText = "<b>System Alert:</b>\n" . $safeMessage;

        try {
            $response = $this->telegram->sendRequest('sendMessage', [
                'chat_id' => $chatId,
                'text' => $formattedText,
                'parse_mode' => 'HTML',
            ]);

            if ($response['ok'] ?? false) {
                return ['success' => true];
            }

            return [
                'success' => false,
                'error' => $response['description'] ?? 'Unknown Telegram API error.',
            ];
        } catch (\Exception $e) {
            Yii::error("Failed to send alert: " . $e->getMessage(), __METHOD__);
            return [
                'success' => false,
                'error' => 'An internal error occurred while sending the message.',
            ];
        }
    }
}

Production Considerations and Edge Cases

While the retry logic in our TelegramClient handles temporary rate limits, it is important to understand the constraints of the Telegram Bot API in a production environment:

Webhook Timeouts: If you are calling TelegramClient inside a webhook handler, you must respond to Telegram's incoming request with an HTTP 200 OK within a few seconds. If your outbound API call gets delayed by rate limits or network latency, Telegram will assume your webhook timed out and will retry sending the update. To prevent this, offload outbound API calls to a background queue (such as yii2-queue) rather than executing them synchronously within the webhook request cycle.
Idempotency: When processing incoming webhook updates, always store the processed update_id in a fast-access storage layer like Redis or a database table with a unique constraint. This prevents your application from executing duplicate actions if Telegram retries a webhook delivery.
Global Rate Limits: Telegram limits bots to sending no more than 30 messages per second globally, and no more than 20 messages per minute within a specific group chat. While our 429 retry mechanism mitigates spikes, high-volume applications should implement an outbound message queue with rate-limiting throttling to prevent hitting these limits in the first place.

For more detailed information on managing bot integrations and handling complex payloads, you can read the official documentation at https://botservice.biz/telegram-bot-api.

If you need professional assistance building, scaling, or securing your Telegram integrations, contact BotCreator — studio that ships Telegram bots / Mini Apps.

Send Telegram Messages via cURL in PHP with Robust Error Handling

Serhii — Sat, 19 Sep 2026 16:00:53 +0000

When integrating Telegram notifications into a PHP application, developers often rely on basic file_get_contents calls. While simple, this approach lacks proper timeout management, fails to handle HTTP status codes gracefully, and makes it difficult to debug API-level errors.

This tutorial demonstrates how to build a production-ready wrapper for the Telegram Bot API sendMessage endpoint using native PHP and cURL. We do not claim this is a full-featured SDK; instead, it is a robust, single-purpose implementation designed to be pasted directly into your staging or production environments.

The Core Implementation

To interact with the Telegram Bot API reliably, we must configure explicit connection and execution timeouts, verify the HTTP response status, validate that the response is valid JSON, and inspect the ok field returned by Telegram.

Here is the complete helper function:

<?php

declare(strict_types=1);

/**
 * Sends a message to a Telegram chat via the Bot API.
 *
 * @param string $token The Telegram Bot token.
 * @param int|string $chatId The target chat ID.
 * @param string $text The message text.
 * @param string $parseMode The formatting mode (HTML, MarkdownV2, etc.).
 * @return array The decoded Telegram response.
 * @throws RuntimeException If the request fails, times out, or Telegram returns an error.
 */
function sendTelegramMessage(string $token, int|string $chatId, string $text, string $parseMode = 'HTML'): array
{
    $url = "https://api.telegram.org/bot" . $token . "/sendMessage";

    $payload = [
        'chat_id' => $chatId,
        'text' => $text,
        'parse_mode' => $parseMode,
    ];

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // Prevent the script from hanging indefinitely
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);

    $response = curl_exec($ch);

    if ($response === false) {
        $error = curl_error($ch);
        curl_close($ch);
        throw new RuntimeException("cURL Error: " . $error);
    }

    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode($response, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new RuntimeException(
            "Failed to decode JSON response. Raw response: " . $response . ". JSON Error: " . json_last_error_msg()
        );
    }

    if (!isset($data['ok']) || $data['ok'] !== true) {
        $description = $data['description'] ?? 'Unknown error';
        $errorCode = $data['error_code'] ?? $httpCode;
        throw new RuntimeException("Telegram API Error [{$errorCode}]: {$description}", $errorCode);
    }

    return $data;
}

Formatting with HTML and Escaping Input

When using parse_mode = 'HTML', Telegram requires strict compliance with its supported HTML tags (<b>, <i>, <code>, etc.). If your message contains unescaped characters like <, >, or & that do not form valid, supported tags, Telegram will reject the payload with a 400 Bad Request error.

To prevent this, always pass dynamic user input through htmlspecialchars before interpolating it into your message template.

<?php

require_once 'telegram_helper.php';

// Retrieve the token from environment variables
$token = getenv('TELEGRAM_BOT_TOKEN');
$chatId = getenv('TELEGRAM_CHAT_ID');

if (!$token || !$chatId) {
    die("Configuration error: TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be set.\n");
}

// Dynamic user input that might contain special characters
$userInput = "User <John&Doe> Testing";

// Escape the input safely for HTML parse_mode
$safeInput = htmlspecialchars($userInput, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8');

$message = "<b>System Alert</b>\n";
$message .= "Status: <i>Active</i>\n";
$message .= "Payload: <code>" . $safeInput . "</code>";

try {
    $result = sendTelegramMessage($token, $chatId, $message, 'HTML');
    echo "Message sent successfully. Message ID: " . $result['result']['message_id'] . "\n";
} catch (RuntimeException $e) {
    echo "Error sending message: " . $e->getMessage() . "\n";
}

Production Considerations

Handling Rate Limits (HTTP 429)

If your application sends a high volume of messages, Telegram may return an HTTP status code 429 (Too Many Requests). The response body will contain a retry_after field indicating how many seconds you must wait before retrying. In a production queue worker, you should catch the RuntimeException, inspect the error code, and delay the job execution accordingly.

Handling Blocked Bots (HTTP 403)

If a user has blocked your bot or has not started a conversation with it, Telegram will return an HTTP 403 Forbidden with the description "Forbidden: bot was blocked by the user". Your application should catch this specific error and mark the user's chat ID as inactive in your database to avoid making unnecessary API calls.

Timeouts

We configured CURLOPT_CONNECTTIMEOUT to 5 seconds and CURLOPT_TIMEOUT to 10 seconds. These values ensure that if Telegram's servers experience latency, your PHP process (such as an FPM worker) does not hang indefinitely, which could otherwise lead to resource exhaustion on your web server.

For further details on available parameters and formatting rules, refer to the official documentation at https://botservice.biz/telegram-bot-api.

BotCreator — studio that ships Telegram bots / Mini Apps.

Build a Lightweight Telegram Webhook Handler in Laravel with Queues and Feature Tests

Serhii — Sat, 19 Sep 2026 07:00:28 +0000

Integrating Telegram bots into Laravel applications often leads developers to install heavy third-party SDKs. While these packages provide abstraction, they can introduce maintenance overhead and lag behind the official Telegram Bot API updates.

This tutorial demonstrates how to build a lightweight, dependency-free Telegram webhook integration in Laravel. We will use Laravel's native Http client, secure the endpoint using a secret token, process updates asynchronously using queued jobs, and write a feature test to verify the entire flow.

We do not claim to build a complete SDK replacement or a complex conversational state machine. Instead, we focus on establishing a secure, scalable foundation for receiving and responding to Telegram updates.

1. Configuration and Environment Setup

First, register your Telegram credentials in your configuration files. Avoid calling env() directly outside of configuration files to ensure config caching works correctly.

Add the following block to your config/services.php file:

// config/services.php
return [
    // ... other services
    'telegram' => [
        'bot_token' => env('TELEGRAM_BOT_TOKEN'),
        'webhook_secret' => env('TELEGRAM_WEBHOOK_SECRET'),
    ],
];

Define these variables in your .env file. The TELEGRAM_WEBHOOK_SECRET is an arbitrary string of your choice (1-256 characters, alphanumeric, underscores, and hyphens) used to verify that the webhook request originates from Telegram.

TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
TELEGRAM_WEBHOOK_SECRET=a_secure_random_string_here

2. Creating the Thin HTTP Client

Laravel's Illuminate\Support\Facades\Http client provides a clean wrapper around Guzzle. We can build a thin client class to handle outgoing requests to the Telegram Bot API.

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Response;
use RuntimeException;

class TelegramClient

{
    protected string $baseUrl;

    public function __construct()
    {
        $token = config('services.telegram.bot_token');
        if (!$token) {
            throw new RuntimeException('Telegram Bot Token is not configured.');
        }
        $this->baseUrl = "https://api.telegram.org/bot{$token}/";
    }

    public function sendMessage(array $params): Response
    {
        return Http::timeout(10)
            ->post($this->baseUrl . 'sendMessage', $params);
    }
}

3. Securing the Webhook Controller

Telegram allows you to pass an X-Telegram-Bot-Api-Secret-Token header when setting up your webhook. Your application must verify this header to prevent unauthorized payloads from being processed.

Create a controller to handle the incoming POST request from Telegram:

namespace App\Http\Controllers;

use App\Jobs\ProcessTelegramUpdateJob;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class TelegramWebhookController extends Controller
{
    public function __invoke(Request $request): Response
    {
        $expectedSecret = config('services.telegram.webhook_secret');
        $providedSecret = $request->header('X-Telegram-Bot-Api-Secret-Token');

        if (!$expectedSecret || $providedSecret !== $expectedSecret) {
            return response('Unauthorized', 401);
        }

        $update = $request->all();
        if (!isset($update['update_id'])) {
            return response('Invalid payload', 400);
        }

        // Dispatch to queue to process asynchronously and respond 200 OK immediately
        ProcessTelegramUpdateJob::dispatch($update);

        return response('OK', 200);
    }
}

use App\Http\Controllers\TelegramWebhookController;
use Illuminate\Support\Facades\Route;

Route::post('/telegram/webhook', TelegramWebhookController::class);

Note: Ensure this route is excluded from CSRF protection if you are registering it outside of the api route group.

4. Processing Updates Asynchronously

Telegram expects your webhook endpoint to return a 200 OK response within a few seconds. If your application performs heavy database queries, external API calls, or complex processing, Telegram may timeout and retry sending the same update, causing duplicate executions.

To prevent this, process the update inside a queued job:

namespace App\Jobs;

use App\Services\TelegramClient;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class ProcessTelegramUpdateJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public array $update) {}

    public function handle(TelegramClient $telegram): void
    {
        $message = $this->update['message'] ?? null;
        if (!$message || !isset($message['text'], $message['chat']['id'])) {
            return;
        }

        $chatId = $message['chat']['id'];
        $text = $message['text'];

        if ($text === '/start') {
            // Always escape dynamic user input using htmlspecialchars when using HTML parse_mode
            $welcomeText = "Hello! Welcome to our bot.";

            $telegram->sendMessage([
                'chat_id' => $chatId,
                'text' => $welcomeText,
                'parse_mode' => 'HTML',
            ]);
        }
    }
}

5. Writing Feature Tests

Testing webhook integrations without hitting the live Telegram API is critical for CI/CD pipelines. We can use Laravel's Queue::fake() and Http::fake() to assert that our controller behaves correctly and our client sends the expected payloads.

namespace Tests\Feature;

use App\Jobs\ProcessTelegramUpdateJob;
use App\Services\TelegramClient;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Queue;
use Tests\TestCase;

class TelegramWebhookTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        config([
            'services.telegram.bot_token' => 'test-token',
            'services.telegram.webhook_secret' => 'test-secret',
        ]);
    }

    public function test_webhook_dispatches_job_on_valid_secret(): void
    {
        Queue::fake();

        $response = $this->postJson('/api/telegram/webhook', [
            'update_id' => 12345,
            'message' => [
                'chat' => ['id' => 999],
                'text' => '/start',
            ],
        ], [
            'X-Telegram-Bot-Api-Secret-Token' => 'test-secret',
        ]);

        $response->assertStatus(200);
        Queue::assertDispatched(ProcessTelegramUpdateJob::class, function ($job) {
            return $job->update['update_id'] === 12345;
        });
    }

    public function test_webhook_rejects_invalid_secret(): void
    {
        Queue::fake();

        $response = $this->postJson('/api/telegram/webhook', [
            'update_id' => 12345,
        ], [
            'X-Telegram-Bot-Api-Secret-Token' => 'wrong-secret',
        ]);

        $response->assertStatus(401);
        Queue::assertNothingDispatched();
    }

    public function test_client_sends_correct_payload(): void
    {
        Http::fake([
            'api.telegram.org/*' => Http::response(['ok' => true, 'result' => []], 200),
        ]);

        $client = new TelegramClient();
        $response = $client->sendMessage([
            'chat_id' => 999,
            'text' => 'Test message',
        ]);

        $this->assertTrue($response->successful());
        Http::assertSent(function ($request) {
            return $request->url() === 'https://api.telegram.org/bottest-token/sendMessage'
                && $request['chat_id'] === 999
                && $request['text'] === 'Test message';
        });
    }
}

Production Considerations

Idempotency: Telegram may occasionally send the same update twice. To handle this, store processed update_id values in a fast storage layer like Redis or a database table with a unique index, and check against it before processing the update in your job.
Rate Limiting: Telegram limits outgoing messages to 30 messages per second. If your application scales, implement a rate-limiting queue worker or use a middleware to throttle outgoing API calls.

BotCreator — studio that ships Telegram bots / Mini Apps.

Set Up a Secure and Idempotent Telegram Webhook in Pure PHP

Serhii — Fri, 18 Sep 2026 17:05:03 +0000

Setting up a Telegram webhook in pure PHP requires more than just pointing a URL to a script. To build a production-ready endpoint, you must secure incoming requests, handle network retries gracefully without duplicating actions (idempotency), and respond quickly to prevent Telegram from retrying the connection.

This guide covers how to register a webhook with a secret token, validate incoming payloads, enforce idempotency using a MySQL database, and return a fast HTTP 200 OK response. We do not cover complex queue systems or framework-specific routing; this is a clean, native PHP implementation designed for direct deployment.

Step 1: Registering the Webhook with a Secret Token

To prevent unauthorized actors from hitting your webhook endpoint, you must specify a secret_token when calling the setWebhook method. Telegram will include this token in the X-Telegram-Bot-Api-Secret-Token header of every request.

The following CLI script registers your webhook. Run this once from your terminal or deployment pipeline.

<?php
// register.php

$botToken = getenv('TELEGRAM_BOT_TOKEN');
$webhookUrl = 'https://yourdomain.com/webhook.php';
$secretToken = getenv('TELEGRAM_SECRET_TOKEN'); // A secure random string (1-256 characters)

if (!$botToken || !$secretToken) {
    die("Missing environment variables: TELEGRAM_BOT_TOKEN or TELEGRAM_SECRET_TOKEN.\n");
}

$url = "https://api.telegram.org/bot{$botToken}/setWebhook";
$payload = [
    'url' => $webhookUrl,
    'secret_token' => $secretToken,
    'allowed_updates' => ['message', 'callback_query']
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    die('cURL Error: ' . curl_error($ch) . "\n");
}
curl_close($ch);

if ($httpStatus !== 200) {
    die("HTTP Error {$httpStatus}: {$response}\n");
}

$result = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    die("Failed to parse JSON response.\n");
}

if (!($result['ok'] ?? false)) {
    die("Telegram API Error: " . ($result['description'] ?? 'Unknown error') . "\n");
}

echo "Webhook successfully registered.\n";

Step 2: Database Schema for Idempotency

Telegram guarantees "at least once" delivery. If your server takes too long to respond, or if a network hiccup occurs, Telegram will retry sending the same update. To prevent processing the same message multiple times, you must track processed update_id values.

Create a dedicated table with a primary key constraint on update_id:

CREATE TABLE `telegram_processed_updates` (
    `update_id` BIGINT UNSIGNED NOT NULL,
    `processed_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`update_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Step 3: The Webhook Handler

The webhook handler must perform four critical tasks:

Send a fast HTTP 200 OK response to Telegram so it closes the connection.
Validate the incoming X-Telegram-Bot-Api-Secret-Token header.
Parse the JSON payload safely.
Perform an atomic database insert to verify idempotency before executing any business logic.

<?php
// webhook.php

// 1. Send fast HTTP 200 OK response
// This releases the connection immediately if PHP-FPM is used.
ob_start();
echo json_encode(['status' => 'ok']);
header('Connection: close');
header('Content-Length: ' . ob_get_length());
header('Content-Type: application/json');
ob_end_flush();
flush();

if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

// 2. Validate Secret Token
$headers = getallheaders();
$receivedToken = $headers['X-Telegram-Bot-Api-Secret-Token'] ?? '';
$expectedToken = getenv('TELEGRAM_SECRET_TOKEN');

if (empty($expectedToken) || !hash_equals($expectedToken, $receivedToken)) {
    http_response_code(403);
    exit('Unauthorized');
}

// 3. Read and parse payload
$rawInput = file_get_contents('php://input');
$update = json_decode($rawInput, true);

if (json_last_error() !== JSON_ERROR_NONE || !isset($update['update_id'])) {
    http_response_code(400);
    exit('Invalid JSON');
}

$updateId = (int)$update['update_id'];

// 4. Enforce Idempotency via Database
$dsn = "mysql:host=" . getenv('DB_HOST') . ";dbname=" . getenv('DB_NAME') . ";charset=utf8mb4";
try {
    $pdo = new PDO($dsn, getenv('DB_USER'), getenv('DB_PASS'), [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]);

    // Attempt to insert the update_id
    $stmt = $pdo->prepare("INSERT INTO telegram_processed_updates (update_id) VALUES (:update_id)");
    $stmt->execute([':update_id' => $updateId]);
} catch (PDOException $e) {
    // SQLSTATE 23000 indicates a duplicate key violation (update already processed)
    if ($e->getCode() == 23000) {
        exit('Duplicate update');
    }
    error_log("Database error: " . $e->getMessage());
    exit;
}

// 5. Process the update safely
if (isset($update['message'])) {
    $message = $update['message'];
    $chatId = $message['chat']['id'] ?? null;
    $text = $message['text'] ?? '';

    if ($chatId && $text === '/start') {
        sendTelegramMessage($chatId, "Hello! Your update ID <b>" . htmlspecialchars((string)$updateId, ENT_QUOTES, 'UTF-8') . "</b> was processed securely.");
    }
}

function sendTelegramMessage($chatId, $text) {
    $botToken = getenv('TELEGRAM_BOT_TOKEN');
    $url = "https://api.telegram.org/bot{$botToken}/sendMessage";
    $payload = [
        'chat_id' => $chatId,
        'text' => $text,
        'parse_mode' => 'HTML'
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);

    $response = curl_exec($ch);
    $httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if (!curl_errno($ch) && $httpStatus === 200) {
        $result = json_decode($response, true);
        if (json_last_error() === JSON_ERROR_NONE && !($result['ok'] ?? false)) {
            error_log("Telegram API Error: " . ($result['description'] ?? 'Unknown error'));
        }
    }
    curl_close($ch);
}

Production Notes

Token Security: Always load TELEGRAM_BOT_TOKEN and TELEGRAM_SECRET_TOKEN via environment variables or a secure configuration file. Never commit raw tokens to your repository.
Timing Attacks: The hash_equals() function is used instead of a standard == comparison to prevent timing attacks when validating the secret token.
Database Cleanup: The telegram_processed_updates table will grow over time. Set up a cron job to delete records older than 3 to 7 days, as Telegram will not retry updates older than 24 hours.
Error Logging: Ensure that PHP's error_log is configured correctly. If the database connection fails, you want to log the error without exposing database credentials or stack traces to the client.

BotCreator — studio that ships Telegram bots / Mini Apps.

Implement Telegram Bot Long Polling in PHP for Local Development

Serhii — Fri, 18 Sep 2026 07:00:27 +0000

When developing Telegram bots locally, setting up public HTTPS webhooks usually requires third-party tunneling tools like Ngrok or Cloudflare Tunnels. Long polling via the getUpdates method is a simpler alternative for local development. It allows your local PHP script to pull updates directly from Telegram's servers without exposing a public port.

However, writing a naive long polling loop can lead to high CPU usage, missed updates, or duplicate message processing. This guide demonstrates how to implement a robust CLI-based long polling loop in native PHP that handles timeouts, tracks offsets, and prevents duplicate processing.

The Mechanics of getUpdates

To implement long polling correctly, you must understand three key parameters of the getUpdates method:

offset: Identifier of the first update to be returned. To acknowledge receipt of an update and prevent Telegram from sending it again, you must call getUpdates with an offset equal to last_processed_update_id + 1.
timeout: The timeout in seconds for long polling. By setting this (e.g., to 30), Telegram will keep the connection open for up to 30 seconds if no new updates are available, reducing unnecessary HTTP requests.
limit: Limits the number of updates to be retrieved (1–100).

The Long Polling Script

Create a script named bot.php. This script runs as a persistent CLI process. It uses cURL to poll the Telegram API, dynamically updates the offset, and handles common network and API errors.

<?php
// bot.php

// Retrieve the bot token from environment variables
$token = getenv('TELEGRAM_BOT_TOKEN');
if (!$token) {
    fwrite(STDERR, "Error: TELEGRAM_BOT_TOKEN environment variable is not set.\n");
    exit(1);
}

$offset = 0;
$timeout = 30; // Seconds Telegram should hold the connection open

echo "Starting Telegram long polling loop...\n";

while (true) {
    $url = "https://api.telegram.org/bot{$token}/getUpdates";
    $params = [
        'offset' => $offset,
        'timeout' => $timeout,
        'limit' => 100,
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url . '?' . http_build_query($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // The cURL timeout must be slightly longer than the Telegram API timeout
    curl_setopt($ch, CURLOPT_TIMEOUT, $timeout + 5);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);

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

    if ($response === false) {
        fwrite(STDERR, "cURL Error: {$curlError}. Retrying in 5 seconds...\n");
        sleep(5);
        continue;
    }

    if ($httpCode !== 200) {
        fwrite(STDERR, "HTTP Error: Status code {$httpCode}. Retrying in 5 seconds...\n");
        sleep(5);
        continue;
    }

    $data = json_decode($response, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        fwrite(STDERR, "JSON Decode Error: " . json_last_error_msg() . ". Retrying...\n");
        sleep(5);
        continue;
    }

    if (!isset($data['ok']) || !$data['ok']) {
        $description = $data['description'] ?? 'Unknown error';
        fwrite(STDERR, "Telegram API Error: {$description}. Retrying...\n");
        sleep(5);
        continue;
    }

    $updates = $data['result'] ?? [];
    foreach ($updates as $update) {
        $updateId = $update['update_id'];

        try {
            processUpdate($update);
        } catch (Exception $e) {
            fwrite(STDERR, "Error processing update {$updateId}: " . $e->getMessage() . "\n");
        }

        // Update the offset to acknowledge this update
        $offset = $updateId + 1;
    }
}

function processUpdate(array $update): void {
    if (isset($update['message'])) {
        $message = $update['message'];
        $chatId = $message['chat']['id'] ?? null;
        $text = $message['text'] ?? '';

        if ($chatId && $text) {
            echo "Processed message from Chat ID {$chatId}: " . htmlspecialchars($text) . "\n";
        }
    }
}

To run this script locally, export your bot token and execute the file from your terminal:

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ"
php bot.php

Preventing Duplicate Processing (Idempotency)

In a standard long polling loop, if your script fetches a batch of 10 updates, successfully processes 5 of them, and then crashes or encounters a network timeout before sending the next getUpdates request, Telegram will re-deliver all 10 updates on the next cycle. This leads to duplicate processing.

To prevent this, you should track processed update_ids in a persistent storage layer (such as SQLite or Redis) and check them before executing any business logic.

Here is how to implement a lightweight SQLite-based idempotency check:

function isUpdateProcessed(int $updateId): bool {
    static $db = null;
    if ($db === null) {
        $db = new PDO('sqlite:' . __DIR__ . '/processed_updates.sqlite');
        $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
        $db->exec("CREATE TABLE IF NOT EXISTS processed (update_id INTEGER PRIMARY KEY, processed_at TEXT)");
    }

    try {
        $stmt = $db->prepare("INSERT INTO processed (update_id, processed_at) VALUES (:id, datetime('now'))");
        $stmt->execute([':id' => $updateId]);
        return false; // Not processed before, successfully inserted
    } catch (PDOException $e) {
        // Integrity constraint violation means the update_id already exists
        if ($e->getCode() === '23000') {
            return true;
        }
        throw $e;
    }
}

Integrate this check at the beginning of your processUpdate function:

function processUpdate(array $update): void {
    $updateId = $update['update_id'];

    if (isUpdateProcessed($updateId)) {
        echo "Update {$updateId} already processed. Skipping.\n";
        return;
    }

    // Proceed with business logic...
}

When to Switch to Webhooks

While long polling is ideal for local development, it is rarely suitable for production environments for several reasons:

Concurrency: Long polling processes updates sequentially in a single thread. Webhooks allow your web server (Nginx/Apache) to handle thousands of incoming updates concurrently using PHP-FPM workers.
Resource Consumption: Keeping a persistent CLI script running requires process monitoring (like Supervisor) and holds open network connections continuously.
Latency: Webhooks deliver updates instantly as they happen, whereas long polling introduces a slight delay depending on the poll interval and network round-trips.

For production deployments, configure a webhook using the setWebhook method and secure it with a secret_token header to verify that incoming requests originate from Telegram.

For further reading on managing production webhooks, security headers, and API limits, refer to the guides at https://botservice.biz/telegram-bot-api.

BotCreator — studio that ships Telegram bots / Mini Apps.

Secure and Queue Telegram Webhooks in Laravel with Redis Idempotency

Serhii — Thu, 17 Sep 2026 16:00:26 +0000

When building production-ready Telegram bots, handling webhooks efficiently is critical. Telegram expects your server to respond with an HTTP 200 OK status quickly. If your application performs database queries, external API calls, or heavy processing synchronously within the request cycle, you risk timing out. This causes Telegram to retry sending the same update, leading to duplicate processing.

This tutorial demonstrates how to build a robust Telegram webhook ingestion pipeline in Laravel. We will secure the endpoint using a custom middleware that validates Telegram's secret token, dispatch incoming payloads to a queued job, and enforce strict idempotency using Redis to prevent processing duplicate updates.

We do not cover setting up a full bot framework or managing long-running worker daemons here; we focus strictly on the webhook ingestion layer.

Step 1: Secure the Webhook with Middleware

When registering your webhook with the Telegram Bot API via setWebhook, you can specify a secret_token (a string containing A-Z, a-z, 0-9, _, and -). Telegram will include this token in every webhook request under the X-Telegram-Bot-Api-Secret-Token header. This allows you to verify that incoming requests originate from Telegram.

First, add your secret token to your config/services.php file:

// config/services.php
return [
    // ...
    'telegram' => [
        'bot_token' => env('TELEGRAM_BOT_TOKEN'),
        'secret_token' => env('TELEGRAM_WEBHOOK_SECRET'),
    ],
];

Next, create a middleware to validate this header:

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class VerifyTelegramSecret
{
    public function handle(Request $request, Closure $next): Response
    {
        $header = $request->header('X-Telegram-Bot-Api-Secret-Token');
        $secret = config('services.telegram.secret_token');

        if (!$secret || $header !== $secret) {
            return response()->json(['error' => 'Unauthorized'], 403);
        }

        return $next($request);
    }
}

Step 2: Define the Route and Dispatch the Job

To keep the HTTP response time as low as possible, the controller or route closure should only validate the basic payload structure, dispatch a queued job, and immediately return an HTTP 200 OK response.

Define the route in routes/api.php:

use App\Http\Middleware\VerifyTelegramSecret;
use App\Jobs\ProcessTelegramUpdate;
use Illuminate\Support
use Illuminate\Support\Facades\Route;
use Illuminate\Http\Request;

Route::post('/telegram/webhook', function (Request $request) {
    $payload = $request->all();

    if (!isset($payload['update_id'])) {
        return response()->json(['error' => 'Malformed payload'], 400);
    }

    // Dispatch the job to the queue
    ProcessTelegramUpdate::dispatch($payload);

    return response()->json(['status' => 'queued'], 200);
})->middleware(VerifyTelegramSecret::class);

Step 3: Implement the Queued Job with Redis Idempotency

Telegram guarantees at-least-once delivery. Network hiccups, temporary timeouts, or worker restarts can cause Telegram to redeliver an update that your application has already processed. To prevent duplicate side effects (such as charging a user twice or sending duplicate messages), you must track processed update_id values.

We will use Redis to store processed update_id keys with a 24-hour expiration window. Using SET with the NX (Set if Not Exists) option ensures atomic verification and locking.

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support
use Illuminate\Support\Facades\Redis;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Http;

class ProcessTelegramUpdate implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(protected array $payload) {}

    public function handle(): void
    {
        $updateId = $this->payload['update_id'] ?? null;
        if (!$updateId) {
            return;

        }

        $lockKey = "tg_update:{$updateId}";

        // Set key with 24-hour expiration (86400 seconds), only if it does not exist (NX)
        $acquired = Redis::set($lockKey, '1', 'EX', 86400, 'NX');

        if (!$acquired) {
            Log::info("Duplicate Telegram update ignored: {$updateId}");
            return;
        }

        try {
            $this->process($this->payload);
        } catch (\Throwable $e) {
            // If processing fails, delete the lock so the retried job can run again
            Redis::del($lockKey);
            throw $e;
        }
    }

    protected function process(array $payload): void
    {
        if (isset($payload['callback_query'])) {
            $this->handleCallbackQuery($payload['callback_query']);
        }

        // Handle other update types (message, edited_message, etc.) here
    }

    protected function handleCallbackQuery(array $callbackQuery): void
    {
        $callbackId = $callbackQuery['id'];
        $data = $callbackQuery['data'] ?? '';

        // Ensure callback_data is within the 64-byte limit during your bot design
        if (strlen($data) > 64) {
            Log::warning("Callback data exceeds 64 bytes: {$data}");
        }

        // Always answer callback queries to remove the loading state on the user's client
        $this->answerCallbackQuery($callbackId, 'Action processed successfully.');
    }

    protected function answerCallbackQuery(string $callbackId, string $text): void
    {
        $token = config('services.telegram.bot_token');

        $response = Http::timeout(5)
            ->post("https://api.telegram.org/bot{$token}/answerCallbackQuery", [
                'callback_query_id' => $callbackId,
                'text' => $text,
            ]);

        if ($response->failed()) {
            Log::error("Failed to answer callback query {$callbackId}: " . $response->body());
        }
    }
}

Production Considerations

When running this architecture in production, ensure your queue worker is configured correctly. If you are using the database queue driver, ensure your database can handle the concurrent write load. For high-throughput environments, the Redis queue driver is highly recommended.

If you are sending HTML formatted messages back to users, always sanitize dynamic user input using htmlspecialchars() before embedding it in your payload to prevent parsing errors on Telegram's side.

Need assistance building or scaling your Telegram integrations? Contact BotCreator — studio that ships Telegram bots / Mini Apps.

Build a Telegram Mini App with Vue 3: WebApp, Theme, and Data Transfer

Serhii — Thu, 17 Sep 2026 07:03:14 +0000

Building a Telegram Mini App with Vue 3 involves integrating the Telegram WebApp JavaScript API, managing the user interface based on the Telegram theme, handling viewport changes, and securely communicating data back to your bot. This tutorial focuses on the client-side Vue 3 implementation, covering the essential steps for setting up your Mini App and sending data. We will not cover the server-side bot implementation in detail, but we will discuss the principles of initData validation.

1. Setting up the Vue 3 Project

First, ensure you have a basic Vue 3 project set up. You can create one using Vite:

npm init vue@latest
# Follow the prompts, choose Vue Router if you need routing
cd your-mini-app
npm install
npm run dev

This will give you a standard Vue 3 application. The next step is to integrate the Telegram WebApp script.

2. Integrating Telegram WebApp JS

Telegram Mini Apps run within a special WebView that injects the Telegram.WebApp object into the global scope. To access its functionalities, you need to include the Telegram WebApp script in your index.html file. It's crucial to load this script before your Vue application script so that Telegram.WebApp is available when your Vue components mount.

Modify your public/index.html (or index.html in the root for Vite projects) to include the script:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <link rel="icon" href="/favicon.ico">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Telegram Mini App</title>
    <script src="https://telegram.org/js/telegram-web-app.js"></script>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

Important Note: The telegram-web-app.js script is only available when your Mini App is opened within Telegram. When developing locally in a browser, Telegram.WebApp will be undefined. You'll need to handle this gracefully in your code, typically by checking window.Telegram?.WebApp before accessing its properties or methods.

3. Initializing and Accessing WebApp Properties in Vue

Once the script is loaded, you can access Telegram.WebApp within your Vue components. A good practice is to create a composable or a global plugin to manage its state and reactivity.

Let's create a simple composable useWebApp.js:

// src/composables/useWebApp.js
import { ref, onMounted, onUnmounted, readonly } from 'vue';

export function useWebApp() {
  const webApp = ref(null);
  const themeParams = ref({});
  const viewportHeight = ref(window.innerHeight);
  const viewportStableHeight = ref(window.innerHeight);

  const initWebApp = () => {
    if (window.Telegram?.WebApp) {
      webApp.value = window.Telegram.WebApp;
      webApp.value.ready(); // Notify Telegram that the Mini App is ready
      themeParams.value = webApp.value.themeParams;
      viewportHeight.value = webApp.value.viewportHeight;
      viewportStableHeight.value = webApp.value.viewportStableHeight;

      // Set the background color to match Telegram's theme
      document.body.style.backgroundColor = webApp.value.themeParams.bg_color;

      // Event listeners for theme and viewport changes
      webApp.value.onEvent('themeChanged', handleThemeChanged);
      webApp.value.onEvent('viewportChanged', handleViewportChanged);

      // Optional: Expand the Mini App to full height if needed
      // webApp.value.expand();
    } else {
      console.warn('Telegram WebApp object not found. Running in standalone browser mode.');
      // Provide mock data for local development if necessary
      themeParams.value = {
        bg_color: '#ffffff',
        text_color: '#000000',
        hint_color: '#808080',
        link_color: '#2481cc',
        button_color: '#2481cc',
        button_text_color: '#ffffff'
      };
    }
  };

  const handleThemeChanged = () => {
    if (webApp.value) {
      themeParams.value = webApp.value.themeParams;
      document.body.style.backgroundColor = webApp.value.themeParams.bg_color;
    }
  };

  const handleViewportChanged = () => {
    if (webApp.value) {
      viewportHeight.value = webApp.value.viewportHeight;
      viewportStableHeight.value = webApp.value.viewportStableHeight;
    }
  };

  onMounted(() => {
    initWebApp();
  });

  onUnmounted(() => {
    if (webApp.value) {
      webApp.value.offEvent('themeChanged', handleThemeChanged);
      webApp.value.offEvent('viewportChanged', handleViewportChanged);
    }
  });

  return {
    webApp: readonly(webApp),
    themeParams: readonly(themeParams),
    viewportHeight: readonly(viewportHeight),
    viewportStableHeight: readonly(viewportStableHeight),
  };
}

Now, in your App.vue or any component, you can use this composable:

<script setup>
import { useWebApp } from './composables/useWebApp';
import { ref, computed } from 'vue';

const { webApp, themeParams, viewportHeight, viewportStableHeight } = useWebApp();

const message = ref('');

const sendDataToBot = () => {
  if (webApp.value) {
    // Ensure data is a string. JSON.stringify is common.
    webApp.value.sendData(JSON.stringify({ type: 'user_message', payload: message.value }));
    webApp.value.close(); // Optionally close the Mini App after sending data
  } else {
    console.warn('Cannot send data: Telegram WebApp not available.');
    alert('Simulating data send: ' + message.value);
  }
};

const mainButtonText = computed(() => {
  return webApp.value?.MainButton.text || 'Send Data';
});

const showMainButton = () => {
  if (webApp.value) {
    webApp.value.MainButton.setText('Submit Message');
    webApp.value.MainButton.show();
    webApp.value.MainButton.onClick(sendDataToBot);
  }
};

// Call showMainButton when the component is mounted or when conditions are met
// For simplicity, we'll call it directly here. In a real app, you might trigger it
// based on user input or form validity.
import { onMounted } from 'vue';
onMounted(() => {
  showMainButton();
});

</script>

<template>
  <div :style="{ backgroundColor: themeParams.bg_color, color: themeParams.text_color, minHeight: viewportHeight + 'px' }" class="mini-app-container">
    <h1>My Awesome Mini App</h1>
    <p>Theme Background: {{ themeParams.bg_color }}</p>
    <p>Viewport Height: {{ viewportHeight }}px</p>
    <p>Viewport Stable Height: {{ viewportStableHeight }}px</p>

    <input
      type="text"
      v-model="message"
      placeholder="Enter your message"
      :style="{ backgroundColor: themeParams.bg_color, color: themeParams.text_color, borderColor: themeParams.hint_color }"
    />
    <button
      @click="sendDataToBot"
      :style="{ backgroundColor: themeParams.button_color, color: themeParams.button_text_color }"
    >
      {{ mainButtonText }} (Fallback Button)
    </button>

    <p v-if="webApp?.initData">
      **InitData (for server validation):**
      <textarea readonly :value="webApp.initData" rows="5"></textarea>
    </p>
    <p v-else>
      `initData` is not available in local development. It's crucial for server-side validation.
    </p>
  </div>
</template>

<style scoped>
.mini-app-container {
  padding: 20px;
  font-family: sans-serif;
  display: flex;
  flex-direction: column;
  gap: 15px;
}

input[type="text"],
textarea {
  width: 100%;
  padding: 10px;
  border: 1px solid;
  border-radius: 5px;
  box-sizing: border-box; /* Ensure padding doesn't increase width */
}

button {
  padding: 10px 15px;
  border: none;
  border-radius: 5px;
  cursor: pointer;
  font-size: 16px;
}
</style>

In this example:

We use onMounted to initialize Telegram.WebApp and register event listeners.
webApp.ready() is called to signal to Telegram that the Mini App is loaded and ready to receive events.
themeParams provides colors for bg_color, text_color, etc., allowing your app to adapt to the user's Telegram theme.
viewportHeight and viewportStableHeight are useful for adjusting your layout, especially when the keyboard is open. viewportStableHeight represents the height without accounting for the keyboard.
document.body.style.backgroundColor is set to match the Telegram background color for a seamless experience.
We demonstrate webApp.sendData() to send a stringified JSON object back to the bot. This data will be received by your bot as part of an update object, specifically in message.web_app_data.data.
webApp.MainButton is used for a prominent action button at the bottom of the Mini App. It's generally preferred over a custom button for better UX.

4. Handling `initData` and Server-Side Validation (Optional but Recommended)

Telegram.WebApp.initData contains data about the user, the bot, and the Mini App launch parameters. It's a URL-encoded string that is cryptographically signed. This initData is crucial for server-side validation to ensure that requests coming from your Mini App are legitimate and haven't been tampered with.

When your Mini App sends data to your backend (e.g., via fetch or axios to your own API endpoint, not directly via sendData), you should include webApp.initData in the request headers or body.

Client-side (Vue component):

// ... inside your component where you make an API call
const submitFormToServer = async () => {
  if (!webApp.value) {
    console.warn('Telegram WebApp not available. Cannot send initData.');
    return;
  }

  try {
    const response = await fetch('/api/submit-data', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Telegram-Init-Data': webApp.value.initData // Send initData in a header
      },
      body: JSON.stringify({ userMessage: message.value, someOtherField: 'value' })
    });

    if (response.ok) {
      const result = await response.json();
      console.log('Server response:', result);
      webApp.value.showAlert('Data sent successfully!');
      webApp.value.close();
    } else {
      const errorData = await response.json();
      console.error('Server error:', errorData);
      webApp.value.showAlert('Failed to send data: ' + (errorData.message || 'Unknown error'));
    }
  } catch (error) {
    console.error('Network or client error:', error);
    webApp.value.showAlert('An error occurred. Please try again.');
  }
};

// You would call submitFormToServer instead of sendDataToBot for API interactions

Server-side (Conceptual PHP example for validation):

<?php
// This is a conceptual example for server-side validation.
// In a real application, use a robust framework and environment variables for the bot token.

function validateTelegramInitData(string $initData, string $botToken): bool
{
    $data = [];
    parse_str($initData, $data);

    if (!isset($data['hash'])) {
        return false; // Hash is missing
    }

    $hash = $data['hash'];
    unset($data['hash']);

    // Sort data keys alphabetically and reconstruct the data string
    ksort($data);
    $dataCheckString = [];
    foreach ($data as $key => $value) {
        $dataCheckString[] = "{$key}={$value}";
    }
    $dataCheckString = implode("\n", $dataCheckString);

    // Calculate secret key
    $secretKey = hash_hmac('sha256', $botToken, 'WebAppData', true);

    // Calculate hash of the data check string
    $calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey);

    // Compare calculated hash with the received hash
    return $calculatedHash === $hash;
}

// Example usage in an API endpoint:
// $initData = $_SERVER['HTTP_X_TELEGRAM_INIT_DATA'] ?? '';
// $botToken = getenv('TELEGRAM_BOT_TOKEN'); // Always use environment variables!

// if (empty($initData) || !validateTelegramInitData($initData, $botToken)) {
//     http_response_code(403);
//     echo json_encode(['message' => 'Invalid initData or unauthorized.']);
//     exit;
// }

// Process your form data here...
// echo json_encode(['status' => 'success', 'message' => 'Data received and validated.']);

?>

This server-side validation ensures that the initData has not been tampered with and originates from Telegram. The botToken used for validation must be the exact token of the bot that launched the Mini App.

5. Production Considerations

HTTPS: Your Mini App must be served over HTTPS. Telegram will not load HTTP Mini Apps.
Error Handling: Implement robust error handling for Telegram.WebApp calls and API requests.
Loading States: Show loading indicators while data is being fetched or sent.
User Feedback: Use webApp.showAlert(), webApp.showConfirm(), and webApp.showPopup() for user feedback within the Telegram interface.
Main Button: Leverage webApp.MainButton for primary actions. It provides a consistent look and feel and is integrated with Telegram's UI.
Back Button: If your Mini App has multiple views or a navigation history, consider using webApp.BackButton to allow users to navigate back within your app, or webApp.close() to exit.
initDataUnsafe: While initData is for validation, initDataUnsafe provides a parsed object version of the data, which can be convenient for accessing user information directly on the client side (e.g., webApp.initDataUnsafe.user.first_name). However, never trust initDataUnsafe for security-critical operations without server-side validation of the full initData string.

By following these steps, you can build a functional and well-integrated Telegram Mini App using Vue 3, providing a rich user experience directly within Telegram. For further reading on the Telegram Bot API and Mini Apps, you can refer to the official documentation at https://botservice.biz/telegram-bot-api.

This tutorial was brought to you by BotCreator — studio that ships Telegram bots / Mini Apps.

DEV Community: Serhii

Authenticate React Telegram Mini Apps with InitData and JWT

Overview

Architecture

Step 1 – Backend: Receive initData and Issue JWT

Step 2 – Frontend: Send initData from React

Why two headers?

Step 3 – Server-Side Verification Flow

Step 4 – Preventing User ID Spoofing

Production Notes

Further Reading

Build Interactive Telegram Inline Keyboards in PHP

The 64-Byte Callback Data Constraint

Delivering Messages with Inline Keyboards

Processing callback_query and answerCallbackQuery

Editing Messages in Place with editMessageText

Unified Webhook Action Handler

Production Edge Cases and Best Practices

Route Website Form Submissions to Telegram Managers in PHP

1. Setting up the Environment and Telegram Bot

2. Processing Form Submissions

3. Handling the Callback Query (Manager's Action)

4. Production Notes and Considerations

Handle Telegram Bot API Rate Limits and 429 Errors in PHP

Understanding Telegram's Rate Limits

1. Implementing a Rate-Limit Aware HTTP Client

2. Structuring an Outgoing Message Queue

Production Notes

Securely Authenticate Users with the Telegram Login Widget in PHP and Yii2

The Telegram Verification Algorithm

Step 1: Implementing the PHP Validator Class

Step 2: Integrating with Yii2 Controller and Database Mapping

Production Considerations

Build a Resilient Telegram Bot Service Layer in Yii2

Secure Configuration with params-local.php

Implementing the TelegramClient Component

Injecting and Using the Service in a Controller

Production Considerations and Edge Cases

Send Telegram Messages via cURL in PHP with Robust Error Handling

The Core Implementation

Formatting with HTML and Escaping Input

Production Considerations

Handling Rate Limits (HTTP 429)

Handling Blocked Bots (HTTP 403)

Timeouts

Build a Lightweight Telegram Webhook Handler in Laravel with Queues and Feature Tests

1. Configuration and Environment Setup

2. Creating the Thin HTTP Client

3. Securing the Webhook Controller

4. Processing Updates Asynchronously

5. Writing Feature Tests

Production Considerations

Set Up a Secure and Idempotent Telegram Webhook in Pure PHP

Step 1: Registering the Webhook with a Secret Token

Step 2: Database Schema for Idempotency

Step 3: The Webhook Handler

Production Notes

Implement Telegram Bot Long Polling in PHP for Local Development

The Mechanics of getUpdates

The Long Polling Script

Preventing Duplicate Processing (Idempotency)

When to Switch to Webhooks

Secure and Queue Telegram Webhooks in Laravel with Redis Idempotency

Step 1: Secure the Webhook with Middleware

Step 2: Define the Route and Dispatch the Job

Step 3: Implement the Queued Job with Redis Idempotency

Production Considerations

Build a Telegram Mini App with Vue 3: WebApp, Theme, and Data Transfer

1. Setting up the Vue 3 Project

2. Integrating Telegram WebApp JS

3. Initializing and Accessing WebApp Properties in Vue

4. Handling initData and Server-Side Validation (Optional but Recommended)

5. Production Considerations

Processing `callback_query` and `answerCallbackQuery`

Editing Messages in Place with `editMessageText`

4. Handling `initData` and Server-Side Validation (Optional but Recommended)