DEV Community: Serhii

Telegram Mini App shop in Next.js fixing MainButton checkout and iOS viewport

Serhii — Mon, 12 Oct 2026 16:17:50 +0000

Opening: you want to sell goods inside a Telegram Mini App. If you trust the raw initDataUnsafe object that the WebApp sends, a malicious user can forge it and trick your backend into thinking they are a legitimate user, leading to free orders or replay attacks. The fix is to verify the HMAC hash on the server before you enable the MainButton or create an invoice. In this guide we build a complete shop – product list, cart, MainButton‑triggered checkout, and a native Telegram invoice – using Next.js App Router with TypeScript. We also highlight the differences you’ll see between desktop Telegram and the iOS WebView (viewport handling, safe area, theme colour, and back‑button behaviour) so the UI works everywhere.

Setting up the Next.js App Router project

Start with a fresh Next.js app that uses the App Router (Next.js 13+). Install the official Telegram Mini Apps SDK which provides types and helpers for WebApp and the MainButton.

npx create-next-app@latest telegram-shop --ts
cd telegram-shop
npm i @telegram-apps/sdk

Create a .env.local file (never commit it) with your bot token. The token is only needed by the backend route that creates invoices.

BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Next, add a small middleware that validates the initData header sent by the Mini App. We’ll put it in src/middleware.ts (the file lives at the project root).

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import crypto from 'crypto'

// This runs on every request; we only protect API routes.
export function middleware(req: NextRequest) {
  if (req.nextUrl.pathname.startsWith('/api/')) {
    const initData = req.headers.get('x-telegram-init-data')
    if (!initData) {
      return NextResponse.json({ error: 'missing initData' }, { status: 401 })
    }
    // Parse the string into key/value pairs
    const params = new URLSearchParams(initData)
    const hash = params.get('hash')
    if (!hash) {
      return NextResponse.json({ error: 'missing hash' }, { status: 401 })
    }
    // Remove hash from the data_check_string
    params.delete('hash')
    const dataCheckString = Array.from(params.entries())
      .map(([k, v]) => `${k}=${v}`)
      .sort()
      .join('\n')
    const secret = crypto.createHmac('sha256', process.env.BOT_TOKEN!)
      .digest()
    const calculatedHash = crypto.createHmac('sha256', secret)
      .update(dataCheckString, 'utf8')
      .digest('hex')
    if (calculatedHash !== hash) {
      return NextResponse.json({ error: 'invalid hash' }, { status: 401 })
    }
    // Optional: reject stale data (older than 10 minutes)
    const authDate = params.get('auth_date')
    if (authDate) {
      const age = Math.floor(Date.now() / 1000) - Number(authDate)
      if (age > 600) {
        return NextResponse.json({ error: 'stale initData' }, { status: 401 })
      }
    }
  }
  return NextResponse.next()
}

The middleware checks the HMAC, ensures the request is recent, and blocks any tampered initData. With this in place, any API route under /api/ can safely treat the user as authenticated.

Building the product list and cart

We’ll keep product data in a simple file; in a real shop you’d fetch from a CMS or database.

// lib/products.ts
export type Product = {
  id: string
  title: string
  description: string
  price: number // in smallest currency unit (e.g. cents)
  imageUrl: string
}

export const PRODUCTS: Product[] = [
  {
    id: 'p1',
    title: 'Ceramic Mug',
    description: 'White 300 ml mug, dishwasher safe',
    price: 1299,
    imageUrl: 'https://example.com/mug.jpg'
  },
  {
    id: 'p2',
    title: 'Sticker Pack',
    description: 'Five vinyl stickers, weatherproof',
    price: 499,
    imageUrl: 'https://example.com/stickers.jpg'
  },
]

Now create a cart provider that lives above the layout. It stores items as { productId: string, quantity: number } and exposes add/remove helpers.

// app/cart-provider.tsx
'use client'

import { createContext, useContext, useState, ReactNode } from 'react'

type CartItem = { productId: string; quantity: number }
type CartContextType = {
  items: CartItem[]
  add: (productId: string) => void
  remove: (productId: string) => void
  total: number
}

const CartContext = createContext<CartContextType | null>(null)

export function CartProvider({ children }: { children: ReactNode }) {
  const [items, setItems] = useState<CartItem[]>([])

  const add = (productId: string) => {
    setItems(prev => {
      const existing = prev.find(i => i.productId === productId)
      if (existing) {
        return prev.map(i =>
          i.productId === productId
            ? { ...i, quantity: i.quantity + 1 }
            : i
        )
      }
      return [...prev, { productId, quantity: 1 }]
    })
  }

  const remove = (productId: string) => {
    setItems(prev => {
      const existing = prev.find(i => i.productId === productId)
      if (!existing) return prev
      if (existing.quantity === 1) {
        return prev.filter(i => i.productId !== productId)
      }
      return prev.map(i =>
        i.productId === productId
          ? { ...i, quantity: i.quantity - 1 }
          : i
      )
    })
  }

  const total = items.reduce((sum, it) => {
    const prod = PRODUCTS.find(p => p.id === it.productId)
    return sum + (prod ? prod.price * it.quantity : 0)
  }, 0)

  return (
    <CartContext.Provider value={{ items, add, remove, total }}>
      {children}
    </CartContext.Provider>
  )
}

export function useCart() {
  const ctx = useContext(CartContext)
  if (!ctx) throw new Error('useCart must be used within CartProvider')
  return ctx
}

Wrap the layout with this provider.

// app/layout.tsx
import './globals.css'
import type { Metadata } from 'next'
import { CartProvider } from './cart-provider'

export const metadata: Metadata = {
  title: 'Telegram Shop',
  description: 'Buy goods directly inside Telegram',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <CartProvider>{children}</CartProvider>
      </body>
    </html>
  )
}

The product list page reads PRODUCTS and renders a grid. Each card has an “Add to cart” button that calls the cart context.

// app/page.tsx
import { PRODUCTS, type Product } from '@/lib/products'
import { useCart } from '@/cart-provider'

export default function Home() {
  const { add } = useCart()

  return (
    <main style={{ padding: '2rem' }}>
      <h1>Shop</h1>
      <div style={{ display: 'grid', gap: '1.5rem', gridTemplateColumns: 'repeat(auto-fill, minmax(200px, 1fr))' }}>
        {PRODUCTS.map((p: Product) => (
          <article
            key={p.id}
            style={{ border: '1px solid #eee', borderRadius: '8px', overflow: 'hidden', background: '#fff' }}
          >
            <img src={p.imageUrl} alt={p.title} style={{ width: '100%', height: 'auto' }} />
            <div style={{ padding: '1rem' }}>
              <h2 style={{ margin: '0 0 0.5rem' }}>{p.title}</h2>
              <p style={{ margin: '0 0 1rem', fontSize: '0.9rem', color: '#555' }}>{p.description}</p>
              <button
                onClick={() => add(p.id)}
                style={
                  {
                    background: '#0088cc',
                    color: '#fff',
                    border: 'none',
                    padding: '0.5rem 1rem',
                    borderRadius: '4px',
                    cursor: 'pointer',
                  }
                }
              >
                Add to cart ({(p.price / 100).toFixed(2)} €)
              </button>
            </div>
          </article>
        ))}
      </div>
    </main>
  )
}

Adding MainButton and handling checkout

The Mini App SDK provides a MainButton component that renders the native button at the bottom of the WebApp. We must wait until WebApp.ready is true before interacting with it, otherwise the button may be unresponsive.

Create a small reusable component that shows the button when the cart is not empty and disables it while the invoice is being created.

// components/MainButtonCheckout.tsx
'use client'

import { useEffect, useState } from 'react'
import { WebApp, MainButton } from '@telegram-apps/sdk'
import { useCart } from '@/cart-provider'

export default function MainButtonCheckout() {
  const { items, total } = useCart()
  const [loading, setLoading] = useState(false)

  useEffect(() => {
    if (!WebApp.isInitialized) {
      // Wait for the WebApp to be ready
      WebApp.ready()
    }
    // Show the button only when there is something to buy
    if (items.length > 0) {
      MainButton.setText(`Pay €{(total / 100).toFixed(2)}`)
      MainButton.show()
    } else {
      MainButton.hide()
    }
    // Handle click
    const onClick = async () => {
      if (loading || items.length === 0) return
      setLoading(true)
      MainButton.setText('Creating invoice…')
      MainButton.disable()
      try {
        const res = await fetch('/api/create-invoice', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            // send the validated initData so the API can identify the user
            'x-telegram-init-data': window.WebApp.initData,
          },
          body: JSON.stringify({ items }),
        })
        if (!res.ok) throw new Error(`HTTP ${res.status}`)
        const { invoice_url } = await res.json()
        // Open the Telegram invoice modal
        WebApp.openInvoice(invoice_url)
      } catch (err) {
        console.error(err)
        alert('Failed to create invoice')
      } finally {
        setLoading(false)
        MainButton.setText(`Pay €{(total / 100).toFixed(2)}`)
        MainButton.enable()
      }
    }
    MainButton.onClick(onClick)
    return () => MainButton.offClick(onClick)
  }, [items, total, loading])

  return null // the component does not render anything; the SDK draws the button
}

Add this component to the layout so it appears on every page.

// app/layout.tsx (updated)
import './globals.css'
import type { Metadata } from 'next'
import { CartProvider } from './cart-provider'
import MainButtonCheckout from '@/components/MainButtonCheckout'

export const metadata: Metadata = {
  title: 'Telegram Shop',
  description: 'Buy goods directly inside Telegram',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <CartProvider>
          {children}
          <MainButtonCheckout />
        </CartProvider>
      </body>
    </html>
  )
}

Creating Telegram invoice via bot API

When the MainButton is clicked we call a Next.js API route. This route validates the initData (again, via middleware), builds the invoice payload, and asks the Bot API for a payment link.

// app/api/create-invoice/route.ts
import type { NextRequest } from 'next/server'
import { NextResponse } from 'next/server'
import https from 'https'

// Helper to POST to the Bot API
function telegramPost(method: string, payload: any): Promise<any> {
  const data = JSON.stringify(payload)
  return new Promise((resolve, reject) => {
    const req = https.request(
      `https://api.telegram.org/bot${process.env.BOT_TOKEN}/${method}`,
      { method: 'POST', headers: { 'Content-Type': 'application/json' } },
      res => {
        let raw = ''
        res.on('data', chunk => (raw += chunk))
        res.on('end', () => {
          try {
            const parsed = JSON.parse(raw)
            if (!parsed.ok) {
              reject(new Error(parsed.description ?? 'Telegram error'))
            } else {
              resolve(parsed.result)
            }
          } catch (e) {
            reject(e)
          }
        })
      }
    )
    req.on('error', reject)
    req.write(data)
    req.end()
  })
}

export async function POST(req: NextRequest) {
  // Middleware already validated initData, but we still need the user ID
  const initData = req.headers.get('x-telegram-init-data')
  if (!initData) {
    return NextResponse.json({ error: 'missing initData' }, { status: 401 })
  }
  const params = new URLSearchParams(initData)
  const userId = params.get('user')
  if (!userId) {
    return NextResponse.json({ error: 'cannot extract user' }, { status: 400 })
  }
  const { items } = await req.json()
  if (!Array.isArray(items) || items.length === 0) {
    return NextResponse.json({ error: 'empty cart' }, { status: 400 })
  }

  // Build the price list expected by the Bot API
  const priceItems = items.map(it => {
    const prod = PRODUCTS.find(p => p.id === it.productId)
    if (!prod) {
      throw new Error(`Unknown product ${it.productId}`)
    }
    return {
      label: prod.title,
      amount: prod.price * it.quantity // amount in smallest currency unit
    }
  })

  const payload = {
    chat_id: Number(userId),
    title: 'Your Telegram Shop order',
    description: 'Purchase from the Mini App',
    payload: Buffer.from(JSON.stringify({ items })).toString('base64'), // optional custom payload
    provider_token: '', // empty for payments via Telegram Stars (if you enable Stars)
    currency: 'EUR',
    prices: priceItems,
    need_name: false,
    need_phone_number: false,
    need_email: false,
    need_shipping_address: false,
    is_flexible: false,
  }

  try {
    const result = await telegramPost('createInvoiceLink', payload)
    return NextResponse.json({ invoice_url: result })
  } catch (e: any) {
    console.error(e)
    return NextResponse.json({ error: e.message }, { status: 500 })
  }
}

The route returns a URL that the Mini App opens with WebApp.openInvoice. Telegram shows the native payment form; after the user completes the payment you’ll receive a pre_checkout_query and then a successful_payment update in your bot. Handling those updates is outside the Mini App scope but you can set up a webhook for your bot to verify the payment and mark the order as fulfilled.

Desktop vs iOS WebView quirks

When you test the shop you’ll notice three common differences:

Viewport and safe area – On iOS the WebApp renders inside a WKWebView that respects the device’s safe area (the notch, home‑indicator, and rounded corners). If you rely on 100vh for a full‑height layout, the bottom part can be hidden under the indicator. Fix: use height: 100dvh (dynamic viewport height) which is supported in modern browsers, or fallback to height: -webkit-fill-available and add padding-bottom: env(safe-area-inset-bottom) via CSS.
Theme colour – Telegram lets you set the theme colour via the bg_color attribute in the WebApp init data. On desktop the WebApp follows the OS theme, while on iOS it overrides the background with the colour you provide. To avoid a flash of white, set a meta tag early in <head>:

   <meta name="theme-color" content="#0088cc" />

and keep your CSS background matching that colour.

Back‑button behaviour – In the desktop WebApp the browser’s back button navigates the Mini App’s history. In the iOS WebView the hardware back gesture is intercepted by Telegram and closes the WebApp unless you call WebApp.disableBackButton() when you want to keep the user inside the flow (e.g., while showing the invoice). After the invoice is dismissed, re‑enable it with WebApp.enableBackButton().

Add a small effect to handle this:

// app/layout.tsx (inside RootLayout, after MainButtonCheckout)
useEffect(() => {
  if (WebApp.isInitialized) {
    // Show the back button when we are on the product list or cart
    WebApp.enableBackButton()
    // Optional: handle the back event to stay inside the app
    WebApp.onBackButton(() => {
      // navigate back in Next.js router if you have a stack
      // router.back()
    })
  }
}, [])

Production notes

Expiry and replay – The middleware rejects initData older than ten minutes (auth_date). Store the hash you’ve seen in a short‑term cache (Redis) if you want to protect against replay attacks within that window.
MainButton timing – Never call MainButton.show() or set its text before WebApp.ready() resolves. The component above waits for the ready promise.
Idempotency – The invoice creation endpoint should be safe to call multiple times. Because we generate the invoice link from the cart contents, calling it twice with the same cart returns the same URL (Telegram’s API is idempotent for createInvoiceLink). If you later store orders in a database, make the order ID deterministic (e.g., hash of cart + user ID) and check for existing rows before inserting.
Error handling – Always check the HTTP status of the Bot API response and bubble a user‑friendly message. Never expose the raw initData to the client.
Testing – Use the @telegram-apps/sdk in a local dev server (next dev) and open the link t.me/yourbot?start=appdata to launch the Mini App. On iOS, open Telegram, go to the bot, and press “Open Web App” to see the WebView.

You now have a complete, type‑safe Next.js Mini App shop that validates initData, shows a MainButton‑driven checkout, creates a Telegram invoice, and works around the quirks of desktop and iOS WebViews. The same patterns apply to any product catalogue or service you want to sell inside Telegram.

BotCreator — studio that ships Telegram bots / Mini Apps.

Optional further reading:

Stop RAM Exhaustion When Uploading Telegram Media in PHP by Reusing File IDs

Serhii — Sun, 11 Oct 2026 17:12:01 +0000

Imagine running an automated PDF receipt generator or digital asset delivery service inside a Telegram bot built with PHP. Each time a user requests a 15 MB file, your backend opens a file handle, reads the file from disk, and transmits it to Telegram's sendDocument endpoint using multipart/form-data.

At low volume, this approach passes unnoticed. However, under standard production load—such as fifty concurrent users requesting assets during a marketing push—your PHP-FPM worker pool rapidly consumes available RAM. Reading multiple multi-megabyte payloads simultaneously spikes memory allocations, saturates outbound network interfaces, and eventually triggers HTTP 429 rate-limit responses or connection timeouts from the Telegram Bot API.

The Telegram Bot API provides three methods for transmitting media: sending raw binary streams via multipart forms, passing a publicly accessible HTTPS URL, or supplying an existing file_id string. Re-uploading raw binaries for identical files is inefficient and dangerous for server stability. Passing HTTP URLs avoids local upload overhead but introduces external latency and relies on Telegram successfully pulling data from your public web server within strict timeout limits.

To build a resilient media pipeline, you must handle raw uploads through streaming cURL descriptors, enforce exact payload boundary checks, and capture Telegram's returned file_id hashes into a local persistence layer. Reusing these identifiers converts multi-megabyte network transfers into sub-kilobyte string payloads, keeping server RAM flat and response times under 50 milliseconds.

Stream Multipart Media Uploads with Raw cURL and Error Handling

When transmitting local files to Telegram, never load the entire file into a PHP string variable using functions like file_get_contents(). Doing so doubles your script's memory footprint by allocating space for the variable in the PHP engine and again inside cURL's internal payload buffers. Instead, pass a native CURLFile object directly into the payload array. This allows cURL to stream the raw bytes straight from the filesystem disk descriptor.

Every API request must validate three distinct failure layers: transport-level failures (cURL errors), HTTP status codes returned by Telegram's edge servers, and application-level failures denoted by ok: false in the returned JSON body.

Here is a robust helper function for transmitting local media files safely using multipart/form-data:

<?php

declare(strict_types=1);

function sendTelegramDocumentMultipart(
    string $botToken,
    int|string $chatId,
    string $filePath,
    string $caption = ''
): array {
    if (!file_exists($filePath) || !is_readable($filePath)) {
        throw new \InvalidArgumentException("File not found or unreadable: {$filePath}");
    }

    $mimeType = mime_content_type($filePath) ?: 'application/octet-stream';
    $postFilename = basename($filePath);

    // Stream directly from disk without reading the file into PHP string memory
    $cFile = new \CURLFile($filePath, $mimeType, $postFilename);

    $payload = [
        'chat_id' => (string)$chatId,
        'document' => $cFile,
        'parse_mode' => 'HTML',
    ];

    if ($caption !== '') {
        $payload['caption'] = htmlspecialchars($caption, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
    }

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => "https://api.telegram.org/bot{$botToken}/sendDocument",
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $payload,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 60, // Allow sufficient time for multi-megabyte uploads
    ]);

    $rawResponse = curl_exec($ch);
    $curlErrno = curl_errno($ch);
    $curlError = curl_error($ch);
    $httpCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($curlErrno !== 0) {
        throw new \RuntimeException("cURL transport failure ({$curlErrno}): {$curlError}");
    }

    $decoded = json_decode((string)$rawResponse, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new \UnexpectedValueException("Invalid JSON response from Telegram (HTTP {$httpCode})");
    }

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

    return $decoded['result'];
}

This implementation prevents memory bloat by letting cURL stream the file, enforces explicit timeouts, escapes HTML captions securely, and unwraps Telegram's application response.

Select Between Direct URL Passing and Multipart Binaries

Telegram allows developers to pass a URL string (e.g., https://example.com/assets/manual.pdf) instead of raw binary data. When receiving a URL, Telegram's servers attempt to download the target file directly from your web server and cache it on their infrastructure.

While URL passing eliminates local binary upload overhead, it introduces specific limitations that cause subtle production bugs:

Size Limits: Standard bot API endpoints permit uploading files up to 50 MB using multipart HTTP requests. However, when passing a URL, Telegram limits the download to 20 MB max.
Download Timeouts: Telegram's web crawler will abort the request if your origin server takes longer than a few seconds to return the response headers and start streaming.
MIME and Header Strictness: If your web server fails to send a clear Content-Length header or uses non-standard HTTP redirection codes, Telegram rejects the payload with 400 Bad Request: wrong file identifier/HTTP URL specified.

The decision matrix for choosing between URL passing and raw multipart streaming comes down to file size and accessibility:

Upload Method	Max File Size	Memory Footprint	Network Bandwidth	Dependency
URL Reference	20 MB	Minimal	Very Low	Requires Public HTTPS URL
Multipart Binary	50 MB	Low (Streamed)	High	Local Filesystem Access
`file_id` Reference	2000 MB	Negligible	Negligible	Pre-cached Telegram File ID

Before sending a document, evaluate the payload parameters programmatically:

<?php

declare(strict_types=1);

function dispatchTelegramDocument(
    string $botToken,
    int|string $chatId,
    string $source,
    string $caption = ''
): array {
    // Case 1: Source is a remote URL
    if (filter_var($source, FILTER_VALIDATE_URL) !== false) {
        // Enforce scheme security
        $scheme = parse_url($source, PHP_URL_SCHEME);
        if ($scheme !== 'https') {
            throw new \InvalidArgumentException("Telegram requires HTTPS URLs for remote uploads.");
        }

        return sendTelegramPayload($botToken, 'sendDocument', [
            'chat_id' => (string)$chatId,
            'document' => $source,
            'caption' => htmlspecialchars($caption, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
            'parse_mode' => 'HTML',
        ]);
    }

    // Case 2: Source is a local file path
    if (file_exists($source)) {
        $fileSize = filesize($source);
        if ($fileSize === false || $fileSize > 50 * 1024 * 1024) {
            throw new \InvalidArgumentException("Local file exceeds Telegram's 50MB Bot API limit.");
        }

        return sendTelegramDocumentMultipart($botToken, $chatId, $source, $caption);
    }

    // Case 3: Source is assumed to be an existing file_id string
    return sendTelegramPayload($botToken, 'sendDocument', [
        'chat_id' => (string)$chatId,
        'document' => $source,
        'caption' => htmlspecialchars($caption, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
        'parse_mode' => 'HTML',
    ]);
}

function sendTelegramPayload(string $botToken, string $method, array $payload): array
{
    $ch = curl_init("https://api.telegram.org/bot{$botToken}/{$method}");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($payload),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 10,
    ]);

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

    $decoded = json_decode((string)$response, true);
    if (!isset($decoded['ok']) || $decoded['ok'] !== true) {
        $desc = $decoded['description'] ?? 'Unknown Error';
        throw new \DomainException("Telegram API Error ({$httpCode}): {$desc}");
    }

    return $decoded['result'];
}

Cache and Reuse file_id to Skip Media Upload Overhead

When Telegram processes a document or photo, the API response includes a unique file_id inside the document or photo payload array. For photos, Telegram returns multiple size variants; the last array element represents the highest-resolution object.

A file_id is an opaque string that points to the file hosted directly on Telegram's Content Delivery Network (CDN). Re-sending a file using its file_id transfers no local file data. The request payload size drops from tens of megabytes to less than 500 bytes.

To take full advantage of this feature, calculate a unique signature (such as an sha256 hash of the binary file) and store the corresponding file_id in your database or cache key-value store.

Here is a complete, production-ready class that handles media caching, local file hashing, and automated fallback execution:

<?php

declare(strict_types=1);

final class TelegramMediaManager
{
    private string $botToken;
    private \PDO $db;

    public function __construct(string $botToken, \PDO $db)
    {
        $this->botToken = $botToken;
        $this->db = $db;
    }

    public function sendCachedDocument(
        int|string $chatId,
        string $localFilePath,
        string $caption = ''
    ): array {
        if (!file_exists($localFilePath)) {
            throw new \InvalidArgumentException("File does not exist: {$localFilePath}");
        }

        $fileHash = hash_file('sha256', $localFilePath);
        if ($fileHash === false) {
            throw new \RuntimeException("Failed to generate hash for file: {$localFilePath}");
        }

        $cachedFileId = $this->getCachedFileId($fileHash);

        if ($cachedFileId !== null) {
            try {
                // Attempt to send using cached file_id string
                return sendTelegramPayload($this->botToken, 'sendDocument', [
                    'chat_id' => (string)$chatId,
                    'document' => $cachedFileId,
                    'caption' => htmlspecialchars($caption, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
                    'parse_mode' => 'HTML',
                ]);
            } catch (\DomainException $e) {
                // If the cached file_id is stale or invalidated by Telegram, clear cache and continue to re-upload
                $this->invalidateCache($fileHash);
            }
        }

        // Cache miss or stale file_id: Perform full multipart upload
        $result = sendTelegramDocumentMultipart($this->botToken, $chatId, $localFilePath, $caption);

        // Extract file_id from response structure
        $newFileId = $result['document']['file_id'] ?? null;
        if (is_string($newFileId) && $newFileId !== '') {
            $this->storeFileId($fileHash, $newFileId);
        }

        return $result;
    }

    private function getCachedFileId(string $fileHash): ?string
    {
        $stmt = $this->db->prepare('SELECT file_id FROM telegram_media_cache WHERE file_hash = :hash LIMIT 1');
        $stmt Gerard = $stmt->execute([':hash' => $fileHash]);
        $row = $stmt->fetch(\PDO::FETCH_ASSOC);

        return is_array($row) && isset($row['file_id']) ? (string)$row['file_id'] : null;
    }

    private function storeFileId(string $fileHash, string $fileId): void
    {
        $stmt = $this->db->prepare('
            INSERT INTO telegram_media_cache (file_hash, file_id, created_at)
            VALUES (:hash, :file_id, :created_at)
            ON CONFLICT(file_hash) DO UPDATE SET file_id = EXCLUDED.file_id
        ');
        $stmt->execute([
            ':hash' => $fileHash,
            ':file_id' => $fileId,
            ':created_at' => time(),
        ]);
    }

    private function invalidateCache(string $fileHash): void
    {
        $stmt = $this->db->prepare('DELETE FROM telegram_media_cache WHERE file_hash = :hash');
        $stmt->execute([':hash' => $fileHash]);
    }
}

The database schema required to back this caching mechanism in PostgreSQL or SQLite is minimal:

CREATE TABLE IF NOT EXISTS telegram_media_cache (
    file_hash VARCHAR(64) PRIMARY KEY,
    file_id VARCHAR(255) NOT NULL,
    created_at INT NOT NULL
);

Production Notes and Edge Case Recovery

When running media uploads at scale, several edge cases will surface during execution:

1. `file_id` Scope and Invalidation

A file_id is unique to the bot API account that uploaded it. You cannot upload a document with Bot A, extract the file_id, and send that same file_id using Bot B. Additionally, Telegram occasionally updates its internal encryption keys and file reference formats. When this happens, historic file_id strings may cause API requests to fail with 400 Bad Request: wrong remote file identifier. Your code must explicitly catch this error code, purge the cached row, and re-upload the original binary.

2. Timeouts and Network Tuning

Network delays scale with file size. For standard webhook responses or inline query callbacks, you must return an HTTP 200 within 10 seconds to prevent Telegram from re-delivering webhooks. If you trigger an asset upload inline inside the webhook request lifecycle, a 40 MB multipart upload will easily breach this 10-second threshold. Offload binary uploads to an asynchronous queue system (e.g., RabbitMQ, Redis Streams, or Laravel Queues) so the webhook handler acknowledges the request instantly.

3. MIME Type Detection Safety

Never trust client-provided file extensions when generating upload handles. Use native extension functions like mime_content_type() or the finfo extension to analyze the file magic bytes before dispatching. If you attempt to send an invalid image format to sendPhoto, Telegram will return 400 Bad Request: PHOTO_INVALID_DIMENSIONS or 400 Bad Request: IMAGE_PROCESS_FAILED.

If you need a dedicated team to engineer high-throughput bot backends or custom web app integrations, consult BotCreator — studio that ships Telegram bots / Mini Apps.

Exchange Telegram WebApp InitData for Validated JWTs in React and PHP

Serhii — Sun, 11 Oct 2026 08:11:18 +0000

Building a Telegram Mini App with React on the frontend and PHP on the backend often introduces a critical security flaw in session handling. When developers build an internal booking system, VIP store, or customer service desk inside Telegram, they frequently fall into the trap of reading window.Telegram.WebApp.initDataUnsafe.user.id on the client and passing that ID directly in JSON payloads or GET parameters to their backend API.

This architecture allows any user to open Chrome DevTools, inspect network requests, and change the user_id parameter to target another account. By spoofing the user ID, an attacker can read private bookings, drain account balances, or complete actions on behalf of other Telegram users. The initDataUnsafe object exists purely for UI rendering, such as displaying the user's first name while the app boots. It carries no cryptographic signature and must never be trusted for access control.

To secure your backend, your React frontend must extract the raw, unparsed string from window.Telegram.WebApp.initData and send it to your PHP API inside an HTTP authorization header. The backend then verifies the cryptographic hash using your Telegram bot token, enforces time-to-live restrictions on auth_date to prevent replay attacks, and issues a standard JSON Web Token (JWT) for subsequent authenticated API requests.

The Failure Mode: Why Client-Side Auth Collapses

When a Mini App opens inside Telegram, the parent client injects a global JavaScript object at window.Telegram.WebApp. This object contains two distinct properties holding user context: initDataUnsafe and initData.

The initDataUnsafe property contains a pre-parsed JavaScript object:

{
  "query_id": "AAH...",
  "user": {
    "id": 987654321,
    "first_name": "Alex",
    "username": "alex_dev"
  },
  "auth_date": 1710000000,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

If your React application relies on initDataUnsafe, an attacker can write a custom script or use standard HTTP interception tools to submit requests to your PHP endpoint containing modified payloads. Because initDataUnsafe is generated entirely in browser memory, changing user.id from 987654321 to 111111111 requires zero cryptographic effort.

In contrast, window.Telegram.WebApp.initData is an unparsed, raw URL-encoded query string directly created and signed by Telegram's servers:

query_id=AAH...&user=%7B%22id%22%3A987654321...%7D&auth_date=1710000000&hash=e3b0c4...

The hash parameter inside this raw string is an HMAC-SHA256 signature generated using a secret key derived from your bot token. Any modification to the user ID, timestamp, or query parameters inside this string invalidates the hash. Your PHP backend must receive this unaltered string, recalculate the hash using your secret bot token, and reject any request where the hashes do not match exactly.

Step 1: Sending Raw initData from React to Your PHP API

Your React application should never attempt to validate the Telegram hash locally. Front-end code exposes your secret bot token to the browser, which allows anyone to forge valid HMAC signatures.

Instead, create an authentication service in React that retrieves window.Telegram.WebApp.initData, transmits it to a dedicated /api/auth/telegram endpoint in PHP, and stores the resulting session JWT in memory or secure storage.

Here is a complete React custom hook and API utility that extracts the string, sends it securely, and manages authentication state:

// src/hooks/useTelegramAuth.ts
import { useState, useEffect, useCallback } from 'react';

interface AuthResponse {
  token: string;
  user: {
    id: number;
    firstName: string;
    username?: string;
  };
}

declare global {
  interface Window {
    Telegram?: {
      WebApp?: {
        initData: string;
        ready: () => void;
        expand: () => void;
      };
    };
  }
}

export function useTelegramAuth(apiBaseUrl: string) {
  const [token, setToken] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState<boolean>(true);
  const [error, setError] = useState<string | null>(null);

  const authenticate = useCallback(async () => {
    setIsLoading(true);
    setError(null);

    const tg = window.Telegram?.WebApp;

    if (!tg || !tg.initData) {
      setError('Telegram WebApp environment not detected.');
      setIsLoading(false);
      return;
    }

    tg.ready();

    try {
      const response = await fetch(`${apiBaseUrl}/api/auth/telegram`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `TelegramInitData ${tg.initData}`
        }
      });

      if (!response.ok) {
        const errorData = await response.json().catch(() => ({}));
        throw new Error(errorData.error || `Authentication failed with status ${response.status}`);
      }

      const data: AuthResponse = await response.json();
      setToken(data.token);
    } catch (err: unknown) {
      const message = err instanceof Error ? err.message : 'Unknown authentication error';
      setError(message);
    } finally {
      setIsLoading(false);
    }
  }, [apiBaseUrl]);

  useEffect(() => {
    authenticate();
  }, [authenticate]);

  return { token, isLoading, error, refetch: authenticate };
}

Notice that tg.ready() is called, but network traffic is held back until the raw initData string is attached to the request. We pass the data in the Authorization header under a custom scheme (TelegramInitData <raw_string>) to avoid leaking authorization strings inside application logs or GET query parameters.

Step 2: Verifying the HMAC-SHA256 Signature in PHP

To verify the payload on your PHP backend, you must implement the precise cryptographic steps defined by the Telegram Bot API specification:

Parse the incoming raw query string into key-value pairs.
Extract the hash parameter and remove it from the array of parameters to check.
Sort all remaining key-value pairs alphabetically by key.
Format the sorted key-value pairs as key=value strings joined by newline characters (\n). This forms the data_check_string.
Compute a secret key using HMAC-SHA256: HMAC-SHA256("WebAppData", bot_token).
Compute the HMAC-SHA256 hash of data_check_string using the secret key derived in step 5.
Use timing-attack-safe string comparison (hash_equals) to compare the calculated hash against the provided hash.

Below is a production-ready PHP class that executes this verification flow and validates the timestamp:

<?php
// src/Auth/TelegramInitDataValidator.php

namespace App\Auth;

class TelegramInitDataValidator
{
    private string $botToken;
    private int $maxAgeSeconds;

    public function __construct(string $botToken, int $maxAgeSeconds = 86400)
    {
        $this->botToken = $botToken;
        $this->maxAgeSeconds = $maxAgeSeconds;
    }

    /**
     * Validates raw initData string. Returns parsed user array on success.
     *
     * @throws \InvalidArgumentException|\RuntimeException
     */
    public function validate(string $rawInitData): array
    {
        if (empty($rawInitData)) {
            throw new \InvalidArgumentException('InitData string cannot be empty.');
        }

        parse_str($rawInitData, $data);

        if (!isset($data['hash'])) {
            throw new \InvalidArgumentException('Missing hash parameter in initData.');
        }

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

        // Check timestamp freshness to prevent replay attacks
        if (!isset($data['auth_date']) || !is_numeric($data['auth_date'])) {
            throw new \InvalidArgumentException('Missing or invalid auth_date.');
        }

        $authDate = (int) $data['auth_date'];
        if ((time() - $authDate) > $this->maxAgeSeconds) {
            throw new \RuntimeException('Authentication data is stale (replay attack defense).');
        }

        // Sort parameters alphabetically
        ksort($data);

        // Build data_check_string
        $dataCheckArr = [];
        foreach ($data as $key => $value) {
            $dataCheckArr[] = $key . '=' . $value;
        }
        $dataCheckString = implode("
", $dataCheckArr);

        // Calculate cryptographic keys
        $secretKey = hash_hmac('sha256', $this->botToken, 'WebAppData', true);
        $calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey);

        if (!hash_equals($calculatedHash, $providedHash)) {
            throw new \RuntimeException('HMAC verification failed. Data signature mismatch.');
        }

        // Parse user JSON payload safely
        if (!isset($data['user'])) {
            throw new \InvalidArgumentException('Missing user object in initData.');
        }

        $userData = json_decode($data['user'], true);
        if (json_last_error() !== JSON_ERROR_NONE || !is_array($userData)) {
            throw new \InvalidArgumentException('Malformed user JSON in initData.');
        }

        return $userData;
    }
}

If an attacker alters the user field inside the query string, step 6 generates a completely different hash from providedHash. Step 7 rejects the payload via hash_equals, which runs in constant time to prevent timing side-channel attacks.

Step 3: Swapping Verified Credentials for a Backend JWT

Re-running HMAC verification on every API request is inefficient and forces your React app to store or re-fetch the raw initData payload repeatedly. The clean architectural pattern is to exchange a valid initData check once for an API session token (JWT).

Below is a PHP script handling the /api/auth/telegram route. It receives the Authorization header, runs the validator, generates a signed JWT using standard HMAC-SHA256, and returns it to the client:

<?php
// public/api/auth.php

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

use App\Auth\TelegramInitDataValidator;

header('Content-Type: application/json');

// Extract Authorization header
$authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if (!str_starts_with($authHeader, 'TelegramInitData ')) {
    http_response_code(401);
    echo json_encode(['error' => 'Missing or invalid Authorization header scheme.']);
    exit;
}

$rawInitData = trim(substr($authHeader, 17));
$botToken = getenv('TELEGRAM_BOT_TOKEN');

if (!$botToken) {
    http_response_code(500);
    echo json_encode(['error' => 'Server misconfiguration: missing bot token.']);
    exit;
}

$validator = new TelegramInitDataValidator($botToken, 86400); // 24-hour max age

try {
    $user = $validator->validate($rawInitData);

    // Bind the verified Telegram ID to application logic
    $telegramId = (int) $user['id'];
    $jwtSecret = getenv('JWT_SECRET') ?: 'fallback-secret-change-me';

    // Build JWT payload
    $header = json_encode(['typ' => 'JWT', 'alg' => 'HS256']);
    $payload = json_encode([
        'sub' => $telegramId,
        'first_name' => $user['first_name'] ?? '',
        'iat' => time(),
        'exp' => time() + (3600 * 12) // 12-hour session
    ]);

    $base64UrlHeader = str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($header));
    $base64UrlPayload = str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($payload));

    $signature = hash_hmac('sha256', $base64UrlHeader . "." . $base64UrlPayload, $jwtSecret, true);
    $base64UrlSignature = str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($signature));

    $jwt = $base64UrlHeader . "." . $base64UrlPayload . "." . $base64UrlSignature;

    http_response_code(200);
    echo json_encode([
        'token' => $jwt,
        'user' => [
            'id' => $telegramId,
            'firstName' => $user['first_name'] ?? '',
            'username' => $user['username'] ?? null
        ]
    ]);

} catch (\InvalidArgumentException $e) {
    http_response_code(400);
    echo json_encode(['error' => $e->getMessage()]);
} catch (\RuntimeException $e) {
    http_response_code(403);
    echo json_encode(['error' => $e->getMessage()]);
} catch (\Throwable $e) {
    http_response_code(500);
    echo json_encode(['error' => 'Internal server error.']);
}

Once React receives this token, it stores it in state and attaches Authorization: Bearer <token> to subsequent requests to fetch private user data or perform writes.

Step 4: Making Authenticated API Calls in React

Here is how you consume the issued JWT within a React component. The component blocks user interactions (like submitting a form or clicking the Telegram MainButton) until authentication completes successfully.

// src/components/BookingView.tsx
import React, { useState } from 'react';
import { useTelegramAuth } from '../hooks/useTelegramAuth';

export const BookingView: React.FC = () => {
  const { token, isLoading, error } = useTelegramAuth('https://api.yourdomain.com');
  const [bookingStatus, setBookingStatus] = useState<string | null>(null);
  const [isSubmitting, setIsSubmitting] = useState<boolean>(false);

  const handleCreateBooking = async () => {
    if (!token) return;

    setIsSubmitting(true);
    try {
      const response = await fetch('https://api.yourdomain.com/api/bookings', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${token}`
        },
        body: JSON.stringify({
          slotId: 'slot_9912',
          guests: 2
        })
      });

      if (!response.ok) {
        throw new Error('Booking request failed.');
      }

      const data = await response.json();
      setBookingStatus(`Booking confirmed! Reference ID: ${data.bookingId}`);
    } catch (err: unknown) {
      const message = err instanceof Error ? err.message : 'Error submitting booking';
      setBookingStatus(message);
    } finally {
      setIsSubmitting(false);
    }
  };

  if (isLoading) {
    return <div className="spinner">Authenticating with Telegram...</div>;
  }

  if (error) {
    return <div className="error-banner">Access Denied: {error}</div>;
  }

  return (
    <div className="booking-container">
      <h2>Reserve Your VIP Slot</h2>
      {bookingStatus && <p className="status-message">{bookingStatus}</p>}
      <button 
        onClick={handleCreateBooking} 
        disabled={isSubmitting}
        className="primary-btn"
      >
        {isSubmitting ? 'Processing...' : 'Confirm Booking'}
      </button>
    </div>
  );
};

Production Security Notes

Strict Replay Protection: Setting an auth_date check window is mandatory. If an attacker intercepts a legitimate raw initData payload from network traffic, they can replay that string indefinitely unless your PHP backend rejects timestamps older than your threshold (e.g., 86400 seconds). For strict financial actions, reduce this window to 300 seconds.
Telegram MainButton Timing: Do not bind click event handlers on the native Telegram.WebApp.MainButton to authenticated endpoints before your JWT state is established in React. Disable or hide the MainButton until the backend returns HTTP 200 with a signed token.
Bot Token Isolation: Never leak the Telegram bot token into React build variables (REACT_APP_ or VITE_). The bot token is a master secret used to derive HMAC keys and execute API commands. It must reside exclusively in environment variables on your PHP backend.
Database Identity Mapping: When creating user records on JWT issuance, map your primary keys against the telegram_id explicitly cast as a 64-bit integer (BIGINT in MySQL/PostgreSQL). Avoid standard 32-bit integers, as active Telegram user IDs routinely exceed 2^31 - 1.

Need production-grade architecture for your next launch? Work with BotCreator — studio that ships Telegram bots / Mini Apps.

Prevent Telegram Callback Timeouts and 64-Byte Payload Truncation in PHP

Serhii — Sat, 10 Oct 2026 16:05:08 +0000

Imagine building a real-time order management dashboard inside Telegram for an e-commerce platform or restaurant network. When a customer places an order, your server dispatches an alert message to a staff channel. Attached to this message is an inline keyboard featuring two action buttons: Accept Order and Reject Order.

When a store manager taps Accept Order, the bot must execute three operations: acknowledge the user's touch feedback, update the order status in the database, and replace the inline action buttons with a static confirmation text such as Order #8491 accepted by Manager Alex.

If you implement this naively, two critical technical failures will break your production system:

Payload truncation errors: Telegram strictly limits the callback_data field of inline keyboard buttons to 64 bytes. If you attempt to pass verbose JSON payloads, query strings, or uncompressed UUIDs like action=accept_order&order_id=9f82d103-5182-4112-9102-182930192841, Telegram rejects the message creation with a 400 Bad Request: BUTTON_DATA_INVALID response.
UI freezing and timeouts: When a user taps an inline button, the Telegram client displays a continuous loading spinner over the button until the server explicitly calls the answerCallbackQuery Telegram API method. If your PHP code spends time querying databases or calling third-party API webhooks before acknowledging the event, the client interface hangs for up to 60 seconds before failing with a timeout error.

In this walkthrough, we will design a robust, clean PHP implementation that encodes compressed, ultra-lightweight payload structures, instantly answers incoming callback queries to eliminate client-side UI lag, and safely updates message layouts in-place using editMessageText.

Designing Short Callbacks Under Telegram's 64-Byte Limit

Telegram's InlineKeyboardButton object allows developers to associate arbitrary string data with a button using the callback_data parameter. However, this parameter is subject to an unforgiving strict boundary: maximum 64 bytes in UTF-8 encoding.

Developers migrating from traditional Web development frequently try to pass serialized state or RESTful query strings inside buttons. Let's look at why standard serialized formats fail under this limit:

// Fails: 78 bytes (exceeds 64-byte limit)
{"action":"approve_refund","customer_id":82914,"transaction_id":"tx_928104820"}

// Fails: 68 bytes (exceeds 64-byte limit)
action=approve_refund&customer_id=82914&transaction_id=tx_928104820

To safely operate within Telegram's constraints, you must adopt a segmented, prefix-based schema using single-character delimiters (such as colons or pipes) and shortened action verb mappings.

For example, instead of action=approve_refund, use a short code like a_ref. Instead of storing long database primary keys or descriptive strings in the payload, look up contextual information on the server side using short integer IDs or condensed hexadecimal keys.

// Valid: 21 bytes (well under the 64-byte limit)
ord:acc:82914:928104

The following PHP helper script demonstrates how to assemble a clean inline keyboard payload matrix using cURL to send a message to Telegram, complete with proper status code validation and error checking:

<?php

declare(strict_types=1);

function sendOrderNotification(string $chatId, int $orderId, string $customerName, float $totalAmount): array
{
    $botToken = getenv('TELEGRAM_BOT_TOKEN');
    if (!$botToken) {
        throw new RuntimeException('TELEGRAM_BOT_TOKEN environment variable is missing.');
    }

    // Construct compact callback payloads: verb:action:id
    // "ord:acc:8491" = 12 bytes
    // "ord:rej:8491" = 12 bytes
    $acceptPayload = sprintf('ord:acc:%d', $orderId);
    $rejectPayload = sprintf('ord:rej:%d', $orderId);

    if (strlen($acceptPayload) > 64 || strlen($rejectPayload) > 64) {
        throw new InvalidArgumentException('callback_data string exceeds Telegram 64-byte limit.');
    }

    $keyboard = [
        'inline_keyboard' => [
            [
                ['text' => '✅ Accept Order', 'callback_data' => $acceptPayload],
                ['text' => '❌ Reject Order', 'callback_data' => $rejectPayload],
            ]
        ]
    ];

    $payload = [
        'chat_id' => $chatId,
        'text' => sprintf("<b>New Order #%d</b>\nCustomer: %s\nTotal: $%.2f", $orderId, htmlspecialchars($customerName, ENT_QUOTES, 'UTF-8'), $totalAmount),
        'parse_mode' => 'HTML',
        'reply_markup' => $keyboard,
    ];

    $ch = curl_init(sprintf('https://api.telegram.org/bot%s/sendMessage', $botToken));
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($payload),
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 5,
    ]);

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

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

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

    return $decoded;
}

Handling Callback Queries and Silencing Client UI Spinners

When a user clicks an inline keyboard button, Telegram does not deliver a standard message update object to your webhook. Instead, it dispatches a callback_query object. This object contains:

id: A unique query identifier required to answer the click event.
from: The user object who pressed the button.
message: The original message object to which the keyboard was attached.
data: The exact string payload defined in callback_data.

When Telegram sends this event to your webhook, the client app shows a loading spinner on the button. The app expects your server to call answerCallbackQuery using the unique callback_query_id.

If your code takes too long or forgets to trigger answerCallbackQuery, the Telegram client interface will hang indefinitely until it times out, creating a bad user experience. To fix this, your PHP script must handle the callback query immediately upon processing the incoming webhook.

The snippet below demonstrates reading the raw PHP input stream, validating the callback query payload, and firing an immediate answerCallbackQuery acknowledgment back to Telegram:

<?php

declare(strict_types=1);

function handleIncomingWebhook(): void
{
    $input = file_get_contents('php://input');
    if (!$input) {
        http_response_code(400);
        exit('Empty request body');
    }

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

    // Ensure this update contains a callback query
    if (!isset($update['callback_query'])) {
        http_response_code(200);
        echo 'Ignored non-callback update';
        return;
    }

    $callbackQuery = $update['callback_query'];
    $callbackId = $callbackQuery['id'];
    $rawPayload = $callbackQuery['data'] ?? '';
    $userId = $callbackQuery['from']['id'];
    $userName = $callbackQuery['from']['first_name'] ?? 'Staff';

    // Parse our compressed payload schema: verb:action:id
    $parts = explode(':', $rawPayload);
    if (count($parts) !== 3 || $parts[0] !== 'ord') {
        // Acknowledge invalid button taps with a notification popup alert
        sendAnswerCallbackQuery($callbackId, 'Invalid button action.', true);
        return;
    }

    $action = $parts[1]; // 'acc' or 'rej'
    $orderId = (int)$parts[2];

    // Send immediate acknowledgement toast to clear client loading spinner
    $toastText = ($action === 'acc') ? 'Processing order acceptance...' : 'Processing order rejection...';
    sendAnswerCallbackQuery($callbackId, $toastText, false);

    // Proceed to edit message content and update business logic
    processOrderAction($callbackQuery, $orderId, $action, $userName);
}

function sendAnswerCallbackQuery(string $callbackQueryId, string $text = '', bool $showAlert = false): bool
{
    $botToken = getenv('TELEGRAM_BOT_TOKEN');
    $payload = [
        'callback_query_id' => $callbackQueryId,
        'text' => $text,
        'show_alert' => $showAlert,
    ];

    $ch = curl_init(sprintf('https://api.telegram.org/bot%s/answerCallbackQuery', $botToken));
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($payload),
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 3,
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return $response !== false;
}

Modifying Message UI In-Place with editMessageText

Once answerCallbackQuery acknowledges the user's action, you must update the interface state in Telegram to prevent duplicate taps or double-processing.

Instead of deleting the old message and issuing a new sendMessage call (which clutters chat history and sends duplicate push notifications), use editMessageText. This method allows you to alter the message body and simultaneously pass an empty reply_markup array, stripping the interactive buttons from the chat.

However, a common edge case occurs when calling editMessageText: if you attempt to edit a message with the exact same text and inline keyboard layout that it already contains, Telegram throws an HTTP 400 error containing the string Bad Request: message is not modified.

Your code must gracefully capture and handle this specific error condition so that secondary taps or concurrent requests do not trigger unhandled exceptions in your application error logs.

Here is how to update the original message in-place and remove the action buttons safely:

<?php

declare(strict_types=1);

function processOrderAction(array $callbackQuery, int $orderId, string $action, string $staffName): void
{
    $botToken = getenv('TELEGRAM_BOT_TOKEN');
    $chatId = $callbackQuery['message']['chat']['id'];
    $messageId = $callbackQuery['message']['message_id'];
    $originalText = $callbackQuery['message']['text'] ?? '';

    $statusFormatted = ($action === 'acc') 
        ? sprintf("\n\n<b>Status:</b> ✅ Accepted by %s", htmlspecialchars($staffName, ENT_QUOTES, 'UTF-8'))
        : sprintf("\n\n<b>Status:</b> ❌ Rejected by %s", htmlspecialchars($staffName, ENT_QUOTES, 'UTF-8'));

    $updatedText = $originalText . $statusFormatted;

    $payload = [
        'chat_id' => $chatId,
        'message_id' => $messageId,
        'text' => $updatedText,
        'parse_mode' => 'HTML',
        'reply_markup' => ['inline_keyboard' => []] // Remove keyboard buttons entirely
    ];

    $ch = curl_init(sprintf('https://api.telegram.org/bot%s/editMessageText', $botToken));
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($payload),
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 5,
    ]);

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

    if ($response === false) {
        error_log(sprintf('Failed to edit message %d in chat %d', $messageId, $chatId));
        return;
    }

    $decoded = json_decode($response, true);

    // Handle Telegram's identical content edit exception gracefully
    if ($httpCode !== 200 || !($decoded['ok'] ?? false)) {
        $description = $decoded['description'] ?? '';
        if (str_contains($description, 'message is not modified')) {
            // Message was already updated by another concurrent manager request; safely ignore.
            return;
        }
        error_log(sprintf('Telegram editMessageText error: %s', $description));
    }
}

Production Considerations: Race Conditions, Idempotency, and Failures

When deploying inline keyboards to production environments, technical bugs usually occur around concurrency, network instability, and strict state transitions. Keep these operational realities in mind:

Concurrent Button Taps (Race Conditions)

In a shared manager channel, two team members might hit Accept Order at the exact same fraction of a second. If both requests reach your webhook before the first editMessageText call strips the buttons, your backend logic could process the order twice.

To prevent this issue, wrap state transitions inside atomic database operations or Redis distributed locks:

// Example atomic state reservation
$affectedRows = $db->execute(
    'UPDATE orders SET status = :status, processed_by = :user WHERE id = :id AND status = "pending"',
    [':status' => 'accepted', ':user' => $staffName, ':id' => $orderId]
);

if ($affectedRows === 0) {
    // Another manager already claimed or updated this order
    sendAnswerCallbackQuery($callbackId, 'Order has already been processed by another team member.', true);
    return;
}

Expiry of Historical Message Keys

Telegram inline keyboards do not expire automatically. A user can scroll back through chat history and tap an inline button attached to an order message created three months ago. Ensure your server routing handles stale primary keys cleanly without throwing unhandled exceptions or fatal database errors.

Network Delays and Webhook Deadlocks

Always issue answerCallbackQuery calls with low timeout thresholds (2–3 seconds). If your application performs external HTTP integrations, database transactions, or PDF document generation, perform those long-running tasks asynchronously after delivering the HTTP 200 status code response to Telegram's webhook dispatcher.

If you need a team to build reliable, high-throughput Telegram integrations without running into these API limits, reach out to BotCreator — studio that ships Telegram bots / Mini Apps.

Prevent Unassigned Web Leads: Process Telegram Manager Claim Keyboards in PHP

Serhii — Sat, 10 Oct 2026 07:02:58 +0000

When building website lead collection forms—such as booking forms, request-for-quote pages, or high-touch sales inquiries—developers often route entries directly to a Telegram group or channel where sales managers can react. However, a naïve implementation that directly forwards form payloads to Telegram without persisting state first creates critical operational flaws. First, if the Telegram Bot API suffers transient downtime or returns a rate-limit error, the customer lead is permanently lost. Second, when multiple managers view the same alert in a shared group chat, two representatives frequently attempt to process the exact same submission simultaneously. Without a structured backend transaction and an inline claim mechanism, customer experience suffers due to duplicate outreach.

To resolve this, you must structure the lead intake pipeline into two distinct phases: durable record creation followed by transactional callback handling. In this guide, we will implement a robust PHP pipeline that receives website form data, generates a cryptographically secure 14-character lead ID using bin2hex(random_bytes(7)), persists the record into MySQL before touching the network, and dispatches a formatted alert containing an interactive Telegram inline keyboard. Then, we will build a secure webhook script that processes manager button presses atomically using SQL conditional updates, instantly answers Telegram callback queries, and modifies the chat UI to visually lock the lead.

Step 1: Generating Lead IDs and Persisting Form Submissions

Before contacting the Telegram API, the submission must live safely in your local database. Relying on auto-incrementing integer IDs (such as 12345) inside public or semi-public callback buttons exposes your system to sequence-guessing vectors. Instead, we use bin2hex(random_bytes(7)) to generate a 14-character hex identifier. This string is short enough to respect Telegram's strict 64-byte callback_data ceiling while providing 56 bits of entropy—more than enough to eliminate collision risks across millions of leads.

Let us detail why Telegram's 64-byte limit matters. The callback_data field attached to an InlineKeyboardButton holds metadata passed back to your webhook when clicked. If your string exceeds 64 UTF-8 bytes, Telegram rejects the API request outright with a 400 Bad Request: BUTTON_DATA_INVALID response. Prefixing our action code as take: followed by a 14-character hex string yields take:a1b2c3d4e5f678, consuming only 19 bytes. This leaves abundant room for future action flags or routing codes without breaking Telegram's payload boundary.

Here is the primary database table definition and submission endpoint (submit_lead.php). Notice how we sanitize user inputs using htmlspecialchars() before constructing HTML payloads for Telegram. Passing raw user input into a Telegram message formatted with parse_mode=HTML will crash your API call whenever a customer includes characters like <, >, or & in their message or name.

<?php
// schema.sql
/*
CREATE TABLE leads (
    id VARCHAR(14) PRIMARY KEY,
    customer_name VARCHAR(100) NOT NULL,
    customer_phone VARCHAR(30) NOT NULL,
    message TEXT,
    status ENUM('pending', 'claimed') DEFAULT 'pending',
    manager_id BIGINT NULL,
    manager_name VARCHAR(100) NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
*/

// submit_lead.php
declare(strict_types=1);

$botToken = getenv('TELEGRAM_BOT_TOKEN');
$chatId = getenv('TELEGRAM_MANAGER_CHAT_ID');

if (!$botToken || !$chatId) {
    http_response_code(500);
    echo json_encode(['error' => 'Server misconfiguration: Missing environment variables']);
    exit;
}

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    echo json_encode(['error' => 'Method not allowed']);
    exit;
}

// Extract and validate incoming form data
$rawName = trim($_POST['name'] ?? '');
$rawPhone = trim($_POST['phone'] ?? '');
$rawMessage = trim($_POST['message'] ?? '');

if (empty($rawName) || empty($rawPhone)) {
    http_response_code(400);
    echo json_encode(['error' => 'Name and phone are required fields']);
    exit;
}

// Connect to database
$pdo = new PDO(
    getenv('DB_DSN'),
    getenv('DB_USER'),
    getenv('DB_PASS'),
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
);

// Generate unique 14-char hex lead identifier (7 bytes = 14 hex chars)
$leadId = bin2hex(random_bytes(7));

// 1. Durably store the lead before making external API network calls
$stmt = $pdo->prepare(
    'INSERT INTO leads (id, customer_name, customer_phone, message, status) VALUES (:id, :name, :phone, :msg, "pending")'
);
$stmt->execute([
    ':id' => $leadId,
    ':name' => $rawName,
    ':phone' => $rawPhone,
    ':msg' => $rawMessage
]);

// 2. Prepare sanitized text for Telegram HTML parsing
$safeName = htmlspecialchars($rawName, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$safePhone = htmlspecialchars($rawPhone, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$safeMessage = htmlspecialchars($rawMessage, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');

$text = "<b>📥 New Website Lead</b>\n\n"
      . "<b>ID:</b> <code>{$leadId}</code>\n"
      . "<b>Name:</b> {$safeName}\n"
      . "<b>Phone:</b> {$safePhone}\n";

if (!empty($safeMessage)) {
    $text .= "<b>Message:</b> {$safeMessage}\n";
}

// Build the inline keyboard with 'take:ID' callback data (19 bytes total)
$payload = [
    'chat_id' => $chatId,
    'text' => $text,
    'parse_mode' => 'HTML',
    'reply_markup' => [
        'inline_keyboard' => [
            [
                [
                    'text' => '✋ Claim Lead',
                    'callback_data' => 'take:' . $leadId
                ]
            ]
        ]
    ]
];

// 3. Dispatch payload to Telegram using cURL with explicit error checks
$ch = curl_init("https://api.telegram.org/bot{$botToken}/sendMessage");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_TIMEOUT => 5
]);

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

if ($curlErr !== '') {
    error_log("Telegram API cURL Error: " . $curlErr);
    http_response_code(500);
    echo json_encode(['error' => 'Lead saved, but notification dispatch failed']);
    exit;
}

$responseData = json_decode((string)$response, true);
if ($httpCode !== 200 || !isset($responseData['ok']) || $responseData['ok'] !== true) {
    error_log("Telegram API Error Response: " . $response);
    http_response_code(500);
    echo json_encode(['error' => 'Failed to publish lead to manager channel']);
    exit;
}

echo json_encode(['status' => 'success', 'lead_id' => $leadId]);

Step 2: Atomic State Processing and Preventing Double-Claims

When Telegram alerts arrive in a shared manager chat, multiple sales reps may tap the "✋ Claim Lead" button simultaneously. If your webhook implementation reads the database record, checks status === 'pending', and then performs an update in separate steps, you introduce a race condition. Under concurrent requests, two distinct HTTP calls can read pending at the same time and both assign the lead to different representatives.

To eliminate this, the update query itself must act as the synchronization boundary. We execute an atomic SQL update statement:
UPDATE leads SET status = 'claimed', manager_id = :mid, manager_name = :mname WHERE id = :id AND status = 'pending'.

If two webhook executions occur simultaneously for the same lead_id, MySQL locks the row for the first transaction. The first query updates the row and returns an affected row count of 1. The second query waits for the lock, runs against the newly updated state where status is now 'claimed', and returns an affected row count of 0.

Another crucial rule when handling inline button clicks is invoking answerCallbackQuery. When a manager taps an inline button, the Telegram client displays a spinning loading indicator on the button. If your webhook script fails to call answerCallbackQuery within a few seconds—or crashes due to an unhandled exception—the user interface hangs until it times out. Furthermore, answerCallbackQuery allows you to display a native toast message or alert modal directly inside the manager's Telegram client explaining whether they successfully secured the lead or lost it to a colleague.

Here is the complete webhook handler (webhook.php):

<?php
// webhook.php
declare(strict_types=1);

$botToken = getenv('TELEGRAM_BOT_TOKEN');
$secretToken = getenv('TELEGRAM_WEBHOOK_SECRET');

if (!$botToken || !$secretToken) {
    http_response_code(500);
    exit('Server configuration error');
}

// Validate Telegram Webhook Secret Token header
$incomingSecret = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
if (!hash_equals($secretToken, $incomingSecret)) {
    http_response_code(403);
    exit('Unauthorized request');
}

$rawInput = file_get_contents('php://input');
$update = json_decode((string)$rawInput, true);

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

// We only process callback_query updates in this handler
if (!isset($update['callback_query'])) {
    http_response_code(200);
    echo 'OK';
    exit;
}

$callback = $update['callback_query'];
$callbackId = $callback['id'];
$data = $callback['data'] ?? '';
$from = $callback['from'];
$managerId = $from['id'];
$managerFirstName = $from['first_name'] ?? 'Manager';
$message = $callback['message'] ?? null;

// Verify callback format starts with 'take:'
if (strpos($data, 'take:') !== 0) {
    answerCallback($botToken, $callbackId, 'Unknown command syntax', true);
    http_response_code(200);
    exit;
}

$leadId = substr($data, 5);

// Validate that lead ID matches expected hex format (14 hex chars)
if (!ctype_xdigit($leadId) || strlen($leadId) !== 14) {
    answerCallback($botToken, $callbackId, 'Invalid lead identifier', true);
    http_response_code(200);
    exit;
}

$pdo = new PDO(
    getenv('DB_DSN'),
    getenv('DB_USER'),
    getenv('DB_PASS'),
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
);

// Atomic UPDATE execution to guarantee single ownership
$stmt = $pdo->prepare('
    UPDATE leads 
    SET status = "claimed", manager_id = :mid, manager_name = :mname 
    WHERE id = :id AND status = "pending"
');

$stmt->execute([
    ':mid' => $managerId,
    ':mname' => $managerFirstName,
    ':id' => $leadId
]);

$wasClaimedByMe = ($stmt->rowCount() === 1);

if ($wasClaimedByMe) {
    // Successful claim path
    answerCallback($botToken, $callbackId, '✅ You successfully claimed this lead!');

    // Update chat message to remove action button and show claim info
    if ($message && isset($message['chat']['id'], $message['message_id'])) {
        $chatId = $message['chat']['id'];
        $msgId = $message['message_id'];
        $originalText = $message['text'] ?? '';

        $safeManager = htmlspecialchars($managerFirstName, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
        $updatedText = htmlspecialchars($originalText, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') 
                     . "\n\n<b>📌 Status:</b> Claimed by {$safeManager}";

        editTelegramMessage($botToken, $chatId, $msgId, $updatedText);
    }
} else {
    // Lead was already claimed by another rep or doesn't exist
    $stmtCheck = $pdo->prepare('SELECT manager_name FROM leads WHERE id = :id');
    $stmtCheck->execute([':id' => $leadId]);
    $existing = $stmtCheck->fetch(PDO::FETCH_ASSOC);

    $claimedBy = $existing['manager_name'] ?? 'another manager';
    $safeClaimedBy = htmlspecialchars($claimedBy, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');

    answerCallback($botToken, $callbackId, "⚠️ Lead already claimed by {$safeClaimedBy}", true);
}

http_response_code(200);
echo 'OK';

function answerCallback(string $token, string $callbackId, string $text, bool $showAlert = false): void {
    $ch = curl_init("https://api.telegram.org/bot{$token}/answerCallbackQuery");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'callback_query_id' => $callbackId,
            'text' => $text,
            'show_alert' => $showAlert
        ]),
        CURLOPT_TIMEOUT => 3
    ]);
    curl_exec($ch);
    curl_close($ch);
}

function editTelegramMessage(string $token, $chatId, int $messageId, string $newText): void {
    $ch = curl_init("https://api.telegram.org/bot{$token}/editMessageText");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'chat_id' => $chatId,
            'message_id' => $messageId,
            'text' => $newText,
            'parse_mode' => 'HTML',
            'reply_markup' => ['inline_keyboard' => []]
        ]),
        CURLOPT_TIMEOUT => 3
    ]);
    curl_exec($ch);
    curl_close($ch);
}

Step 3: Production Security and Telegram API Failure Cases

Deploying lead routing solutions into active production requires handling operational edge cases beyond simple happy paths. Here are the essential requirements for keeping this integration reliable:

1. Telegram 64-Byte Callback Limit Budget

Telegram's Bot API silently drops or rejects requests with callback_data larger than 64 bytes. When designing complex callback actions, calculate your string length precisely:

Action prefix (take:): 5 bytes
Unique ID (bin2hex(random_bytes(7))): 14 bytes
Total consumed: 19 bytes (well below the 64-byte threshold).

If you attempt to stuff raw JSON like {"action":"claim","id":"123456789"} into callback_data, you consume 32+ bytes immediately. Adding additional query attributes will push you over the 64-byte boundary, triggering HTTP 400 errors.

2. Secret Token Authentication

Never accept raw webhook POST requests without verifying source authenticity. Attackers who discover your webhook.php public URL can send fake callback_query payloads to mark leads as claimed or alter database states. Always configure a strong secret token during webhook registration:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://yourdomain.com/webhook.php", "secret_token": "YOUR_HIGH_ENTROPY_SECRET_HERE"}'

Your PHP code validates this token via $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] using constant-time string comparison (hash_equals()) before executing any database logic.

3. Immediate HTTP 200 Responses

Telegram expects your webhook endpoint to return a 200 OK status code within 5 seconds. If your database query or downstream logic hangs, Telegram marks the attempt as failed and retries sending the same update multiple times. This can cause duplicate updates to flood your server. Ensure cURL timeout values on outward calls (such as answerCallbackQuery and editMessageText) are capped at 3 seconds, and always return HTTP 200 to Telegram even when handling business-logic failures (such as a lead already being claimed).

If you need tailored messaging infrastructure or full-stack Telegram integration, reach out to BotCreator — studio that ships Telegram bots / Mini Apps.

Prevent Telegram Broadcast Crashes by Handling 429 Retry-After and Queueing in PHP

Serhii — Fri, 09 Oct 2026 16:01:07 +0000

Imagine launching a flash sale for your Telegram-based e-commerce store. You have 5,000 active users who opted in for notifications. To announce the sale, you write a quick PHP script that loops through your database and sends a promotional message to everyone. Within the first three seconds, the script grinds to a halt. Half your users receive the message twice, others don't receive it at all, and your server logs are flooded with HTTP 429 Too Many Requests errors.

This is the reality of ignoring the Telegram Bot API rate limits. Telegram enforces strict limits on how fast your bot can send messages. If you exceed these limits, Telegram throttles your bot, returns a 429 status code, and expects you to back off. If you continue to flood their servers, your bot's API token can be temporarily or permanently restricted.

In this tutorial, we will build a production-ready, rate-aware Telegram message queue in PHP. We will explore why naive loops fail, how to parse and respect Telegram's retry_after parameter, and how to design a database-backed worker that guarantees message delivery without triggering rate limits.

The Naive Loop and Why It Fails

When developers first build a broadcast feature, they often write a simple synchronous loop. They fetch all user IDs from the database and send requests one after another using a standard HTTP client.

Here is an example of this dangerous pattern:

<?php
// naive-broadcast.php
// DO NOT USE THIS IN PRODUCTION

$botToken = getenv('TELEGRAM_BOT_TOKEN');
$users = $db->query("SELECT telegram_id FROM users WHERE notifications_enabled = 1")->fetchAll();
$message = "Our flash sale is live! Use code FLASH20.";

foreach ($users as $user) {
    $url = "https://api.telegram.org/bot{$botToken}/sendMessage";
    $payload = [
        'chat_id' => $user['telegram_id'],
        'text' => $message
    ];

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

    $response = curl_exec($ch);
    curl_close($ch);

    // No rate limit checking, no error handling
}

This script will fail almost immediately due to Telegram's strict rate limits:

Global Limit: A bot can send a maximum of 30 messages per second across all chats combined.
Single Chat Limit: A bot can send only 1 message per second to a specific user or private chat.
Group/Channel Limit: A bot can send a maximum of 20 messages per minute to a specific group or channel.

When you run the naive loop above, your server sends hundreds of requests per second. Telegram will block your requests and return a JSON response that looks like this:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 9",
  "parameters": {
    "retry_after": 9
  }
}

If your script does not read the retry_after value and pause execution, you will continue to hit the API, compounding the block duration. Furthermore, because PHP scripts have execution time limits (e.g., max_execution_time in php.ini), a synchronous loop that gets throttled will eventually time out, leaving your broadcast half-finished with no record of who received the message and who did not.

Building a Rate-Aware HTTP Client

To handle rate limits correctly, we must build an HTTP client wrapper that inspects every response from Telegram. If it encounters an HTTP status code 429, it must parse the retry_after parameter, pause execution for that exact number of seconds, and then retry the request.

Here is a robust PHP class that wraps cURL to handle Telegram rate limits dynamically:

<?php
// TelegramClient.php

class TelegramClient
{
    private string $botToken;
    private int $maxRetries = 3;

    public function __construct(string $botToken)
    {
        $this->botToken = $botToken;
    }

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

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

            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            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_TIMEOUT, 10);

            $responseBody = curl_exec($ch);
            $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            $curlError = curl_errno($ch);
            curl_close($ch);

            if ($curlError !== 0) {
                // Handle network failures with a short backoff
                sleep(2);
                continue;
            }

            $data = json_decode($responseBody, true);
            if (json_last_error() !== JSON_ERROR_NONE) {
                throw new RuntimeException("Invalid JSON response from Telegram API");
            }

            if ($httpCode === 429) {
                $retryAfter = $data['parameters']['retry_after'] ?? 1;
                // Safety margin of 1 second
                sleep($retryAfter + 1);
                // Retry the loop
                continue;
            }

            if ($httpCode !== 200 || ($data['ok'] ?? false) === false) {
                throw new RuntimeException(
                    "Telegram API error: " . ($data['description'] ?? 'Unknown error') . " (Code: {$httpCode})"
                );
            }

            return $data;
        }

        throw new RuntimeException("Failed to execute Telegram API request after {$this->maxRetries} attempts due to rate limits or network issues.");
    }
}

This client ensures that if Telegram tells us to wait, we wait. However, relying solely on this client inside a synchronous loop is still not enough for large-scale broadcasts. If you have 10,000 users and hit a 9-second block, your entire PHP process sleeps, which can cause web requests to time out. We must decouple message generation from message delivery using a queue.

Designing a Database-Backed Queue and Worker

To safely broadcast messages, we need a queue system. When you want to send a broadcast, you insert the messages into a database table with a pending status. A background worker script (running via CLI or a cron job) then processes these messages at a controlled rate, respecting both the global 30 messages/second limit and the 1 message/second per-user limit.

First, let's define the database schema for our queue. This schema tracks the target chat, the message payload, the status, and when the last message was sent to each specific chat to prevent violating the 1 message/second per-user rule.

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, processing, sent, failed
    retry_after_timestamp INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    processed_at TIMESTAMP NULL,
    INDEX idx_status_chat (status, chat_id)
);

CREATE TABLE telegram_chat_throttle (
    chat_id BIGINT PRIMARY KEY,
    last_sent_at DECIMAL(14, 4) NOT NULL -- Unix timestamp with microsecond precision
);

Now, we will write a CLI worker script. This script runs continuously, fetching pending messages and sending them. It uses the telegram_chat_throttle table to ensure we never send more than one message per second to the same user. It also tracks the global rate to ensure we do not exceed 30 requests per second.

<?php
// queue-worker.php

require_once 'TelegramClient.php';

$db = new PDO('mysql:host=127.0.0.1;dbname=bot_db', 'db_user', 'db_password', [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC
]);

$botToken = getenv('TELEGRAM_BOT_TOKEN');
$client = new TelegramClient($botToken);

$globalLimit = 30; // Max messages per second globally
$globalInterval = 1.0 / $globalLimit; // Time to wait between global requests (seconds)

while (true) {
    $startTime = microtime(true);

    // Fetch a batch of pending messages
    $stmt = $db->prepare("
        SELECT q.* 
        FROM telegram_message_queue q
        WHERE q.status = 'pending' 
          AND q.retry_after_timestamp <= :now
        LIMIT 50
    ");
    $stmt->execute(['now' => time()]);
    $batch = $stmt->fetchAll();

    if (empty($batch)) {
        // No messages to process, sleep for a bit and check again
        usleep(500000); // 0.5 seconds
        continue;
    }

    foreach ($batch as $message) {
        $chatId = $message['chat_id'];
        $payload = json_decode($message['payload'], true);
        $now = microtime(true);

        // Check the last time we sent a message to this specific chat
        $throttleStmt = $db->prepare("SELECT last_sent_at FROM telegram_chat_throttle WHERE chat_id = :chat_id");
        $throttleStmt->execute(['chat_id' => $chatId]);
        $lastSent = $throttleStmt->fetchColumn();

        if ($lastSent !== false && ($now - $lastSent) < 1.0) {
            // We sent a message to this user less than 1 second ago. Skip for now.
            continue;
        }

        // Mark as processing to prevent duplicate delivery by concurrent workers
        $updateStmt = $db->prepare("UPDATE telegram_message_queue SET status = 'processing' WHERE id = :id AND status = 'pending'");
        $updateStmt->execute(['id' => $message['id']]);

        if ($updateStmt->rowCount() === 0) {
            // Another worker picked it up
            continue;
        }

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

            // Update throttle timestamp
            $db->prepare("
                INSERT INTO telegram_chat_throttle (chat_id, last_sent_at) 
                VALUES (:chat_id, :now) 
                ON DUPLICATE KEY UPDATE last_sent_at = :now
            ")->execute([
                'chat_id' => $chatId,
                'now' => microtime(true)
            ]);

            // Mark message as sent
            $db->prepare("UPDATE telegram_message_queue SET status = 'sent', processed_at = NOW() WHERE id = :id")
               ->execute(['id' => $message['id']]);

        } catch (RuntimeException $e) {
            // If we hit a rate limit, the client handled the sleep, but we might need to retry later
            // Reset status to pending and set a backoff timestamp
            $db->prepare("
                UPDATE telegram_message_queue 
                SET status = 'pending', retry_after_timestamp = :retry_at 
                WHERE id = :id
            ")->execute([
                'id' => $message['id'],
                'retry_at' => time() + 10 // Backoff for 10 seconds
            ]);
        }

        // Enforce global rate limit (30 requests per second max)
        $elapsed = microtime(true) - $now;
        if ($elapsed < $globalInterval) {
            usleep(($globalInterval - $elapsed) * 1000000);
        }
    }
}

This worker architecture solves several critical issues:

Concurrency Safety: By using a status = 'processing' transition check (rowCount() === 0), you can safely run multiple instances of this worker script in parallel without sending duplicate messages to users.
Per-User Throttling: The telegram_chat_throttle table prevents the worker from sending messages to the same user faster than once per second, even if there are multiple pending messages for that user in the queue.
Global Rate Control: The $globalInterval calculation ensures that the loop pauses slightly between requests, keeping the total request rate safely below the 30 requests/second threshold.

Production Notes

When running a Telegram bot in production, rate limits are not the only hazard. You must also handle webhook timeouts, message formatting, and callback queries correctly to maintain a stable system.

Webhook Execution Limits

When Telegram sends an update to your webhook URL, it expects your server to respond with an HTTP 200 OK status code within a few seconds. If your webhook script takes too long to respond (for example, because it is processing a database query or trying to send multiple API requests synchronously), Telegram will assume your server is down. It will terminate the connection and retry sending the same update repeatedly.

This creates a destructive loop: your server gets overloaded processing duplicate updates, which causes more timeouts.

Rule: Never process broadcasts or heavy operations inside the webhook execution thread. When a webhook receives a command to start a broadcast, it should insert a record into the database queue and immediately return an HTTP 200 OK to Telegram. Let your background CLI workers handle the actual API communication.

Idempotency and Duplicate Prevention

To prevent processing the same webhook update twice, you must track the update_id sent by Telegram. Store the processed update_id values in a database table with a unique constraint, or in Redis with an expiration time of 24 hours. If an incoming webhook contains an update_id that already exists in your store, discard it immediately.

Safe HTML Formatting

If you use parse_mode => 'HTML' in your payloads, any unescaped special characters (like <, >, or &) will cause Telegram to reject the message with an HTTP 400 Bad Request error. This will break your queue worker if it encounters a malformed message. Always wrap dynamic user input in htmlspecialchars() before inserting it into your message payloads:

$safeText = htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');

Handling Callback Queries

When a user clicks an inline keyboard button, Telegram sends a callback_query update to your webhook. The user's Telegram client will display a loading spinner on the button until your bot acknowledges the click. You must call the answerCallbackQuery method immediately after receiving a callback query, even if you do not need to display an alert. This stops the loading spinner and provides a smooth user experience.

To learn more about optimizing your bot's architecture and handling high-volume traffic, you can read about the Telegram Bot API specifications at https://botservice.biz/telegram-bot-api.

BotCreator — studio that ships Telegram bots / Mini Apps.

Stop Spoofed Telegram Logins by Verifying HMAC and Binding IDs in Yii2

Serhii — Fri, 09 Oct 2026 07:00:52 +0000

Integrating the Telegram Login Widget into a Yii2 application is an excellent way to streamline user onboarding. Instead of forcing users to fill out long registration forms, verify email addresses, and create complex passwords, they can authenticate with a single click.

However, implementing this flow incorrectly introduces a critical security vulnerability: account takeover. The Telegram Login Widget operates on the client side, returning user data (such as id, first_name, username, and a cryptographic hash) back to your server via a redirect URL or a JavaScript callback.

If your server simply reads the incoming id parameter and logs the user in, any attacker can easily impersonate any user on your platform. An attacker only needs to know a target's Telegram ID (which is public information) and send a manual request to your callback endpoint with that ID. To prevent this, you must cryptographically verify the data signature on your server using your secret Telegram Bot Token.

This guide walks through setting up a secure verification pipeline in PHP and integrating it into a Yii2 application, covering database migrations, HMAC-SHA-256 verification, replay attack prevention, and account binding.

The Vulnerability: Why Client-Side Data is a Trap

When a user authenticates via the Telegram Login Widget, your callback URL receives a payload that looks like this:

https://example.com/auth/telegram-callback?id=12345678&first_name=John&username=johndoe&photo_url=https%3A%2F%2Ft.me%2Fi%2Fuserpic%2F...&auth_date=1700000000&hash=a1b2c3d4e5f6...

If your application code looks like this:

// DANGER: DO NOT DO THIS
$telegramId = Yii::$app->request->get('id');
$user = User::findOne(['telegram_id' => $telegramId]);
if ($user) {
    Yii::$app->user->login($user);
}

Your application is completely insecure. Anyone can modify the id parameter in their browser address bar to match your administrator's Telegram ID and gain full access to your system.

To secure this flow, Telegram signs the payload. The hash parameter is an HMAC-SHA-256 signature of the other query parameters, signed with a secret key derived from your Telegram Bot Token. Because only your server and Telegram know your Bot Token, a matching hash proves that the data was generated by Telegram and has not been tampered with.

Step 1: Prepare the Database Migration

Before writing the verification logic, your database must be ready to store Telegram user IDs. Telegram user IDs are currently within the 64-bit integer range. Storing them as a standard 32-bit signed integer will cause silent truncation or database errors once an ID exceeds 2,147,483,647.

Run the Yii2 migration generator:

php yii migrate/create add_telegram_id_to_user_table

Modify the generated migration file to add a bigint column and a unique index. The unique index is critical: it prevents multiple local accounts from linking to the same Telegram account, which could otherwise lead to database conflicts or security bypasses.

<?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->bigInteger()->unsigned()->null()->defaultValue(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');
    }
}

Run the migration using the console command:

php yii migrate

Step 2: Implement the Cryptographic Verification Service

To verify the payload, we must reconstruct the data-check string that Telegram signed. The rules for constructing this string are strict:

Extract all query parameters except hash.
Sort the remaining parameters alphabetically by key.
Format each key-value pair as key=value.
Join these pairs with a newline character (\n).

Next, we derive our signing key. Telegram does not use the raw Bot Token directly as the HMAC key. Instead, it uses the SHA-256 hash of the raw Bot Token in binary format. Finally, we calculate the hex-encoded HMAC-SHA-256 of our data-check string using this derived key and compare it to the incoming hash parameter.

We must also enforce an expiration window using the auth_date parameter. If an attacker intercepts a valid, signed redirect URL, they could replay it days or weeks later to log in. Restricting the validity of the signature to a short window (e.g., 24 hours) mitigates this risk.

Here is a complete, reusable PHP service class for this verification:

<?php

namespace app\services;

use Yii;
use yii\base\InvalidArgumentException;

class TelegramAuthService
{
    private string $botToken;
    private int $allowedAge;

    /**
     * @param string $botToken Your secret Telegram Bot Token
     * @param int $allowedAge Maximum age of the authentication request in seconds (default: 24 hours)
     */
    public function __construct(string $botToken, int $allowedAge = 86400)
    { 
        if (empty($botToken)) {
            throw new InvalidArgumentException('Telegram Bot Token cannot be empty.');
        }
        $this->botToken = $botToken;
        $this->allowedAge = $allowedAge;
    }

    /**
     * Validates the incoming Telegram login payload.
     * 
     * @param array $params The query parameters received from the widget
     * @return bool True if the payload is authentic and fresh, false otherwise
     */
    public function validate(array $params): bool
    {
        if (!isset($params['hash']) || !isset($params['auth_date'])) {
            return false;
        }

        // 1. Prevent replay attacks by checking signature age
        $authDate = (int)$params['auth_date'];
        if ((time() - $authDate) > $this->allowedAge) {
            return false;
        }

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

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

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

        // 4. Derive the cryptographic key
        $secretKey = hash('sha256', $this->botToken, true);

        // 5. Calculate the expected hash
        $expectedHash = hash_hmac('sha256', $dataCheckString, $secretKey);

        // 6. Compare hashes using a constant-time comparison function to prevent timing attacks
        return hash_equals($expectedHash, $receivedHash);
    }
}

Step 3: Integrate with Yii2 Controller

Now we will create the controller action to handle the callback. This action must handle two distinct business flows:

Account Binding (Authenticated Users): If a user is already logged in via their standard username/password, they can visit their profile settings and click "Link Telegram". The controller should verify the payload and save their telegram_id to their existing record.
Direct Authentication (Guests): If a guest visits the login page and clicks "Sign in with Telegram", the controller verifies the payload, searches for a user with that telegram_id, and logs them into the application.

Configure your bot token in your Yii2 configuration file (config/params.php or config/web.php):

return [
    'telegramBotToken' => getenv('TELEGRAM_BOT_TOKEN'),
];

Now, implement the AuthController action:

<?php

namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\BadRequestHttpException;
use yii\web\Response;
use app\services\TelegramAuthService;
use app\models\User;

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

        if (!$token) {
            throw new BadRequestHttpException('Telegram authentication is not configured on the server.');
        }

        $authService = new TelegramAuthService($token);

        // Perform cryptographic verification
        if (!$authService->validate($params)) {
            Yii::$app->session->setFlash('error', 'Invalid or expired Telegram authentication signature.');
            return $this->redirect(['site/login']);
        }

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

        // Case 1: User is already logged in, attempting to link their Telegram account
        if (!Yii::$app->user->isGuest) {
            /** @var User $currentUser */
            $currentUser = Yii::$app->user->identity;

            // Check if this Telegram ID is already linked to another account
            $existingBinding = User::findOne(['telegram_id' => $telegramId]);
            if ($existingBinding && $existingBinding->id !== $currentUser->id) {
                Yii::$app->session->setFlash('error', 'This Telegram account is already linked to another user.');
                return $this->redirect(['user/profile']);
            }

            $currentUser->telegram_id = $telegramId;
            if ($currentUser->save(false)) {
                Yii::$app->session->setFlash('success', 'Your Telegram account has been successfully linked.');
            } else {
                Yii::$app->session->setFlash('error', 'Failed to save your Telegram association.');
            }

            return $this->redirect(['user/profile']);
        }

        // Case 2: Guest attempting to log in via Telegram
        $user = User::findOne(['telegram_id' => $telegramId]);
        if (!$user) {
            // Optional: Auto-register the user here if your application allows it.
            // For this example, we require an existing account to be linked first.
            Yii::$app->session->setFlash('error', 'No local account is linked to this Telegram account. Please log in normally and link your Telegram profile.');
            return $this->redirect(['site/login']);
        }

        // Log the user in
        if (Yii::$app->user->login($user, 3600 * 24 * 30)) {
            Yii::$app->session->setFlash('success', 'Successfully logged in via Telegram.');
            return $this->goBack();
        }

        Yii::$app->session->setFlash('error', 'An error occurred during login.');
        return $this->redirect(['site/login']);
    }
}

Production Considerations & Edge Cases

When deploying this authentication flow to production, keep the following security and operational practices in mind:

Timing Attack Prevention: Always use hash_equals() instead of the standard == or === operators when comparing the generated hash with the incoming hash. Standard string comparisons return false as soon as a character mismatch is found, which allows attackers to deduce the signature character-by-character by measuring response times.
Strict Database Types: Always enforce unsigned and bigInteger for the telegram_id column. If your database driver attempts to cast a large Telegram ID into a standard 32-bit signed integer, it can overflow, causing multiple users to resolve to the same truncated ID, leading to critical account cross-overs.
Handling Username Changes: The Telegram Login Widget returns the user's current Telegram username. If you store this username in your database for display purposes, update it during every successful login. Users change their Telegram handles frequently, and displaying stale handles can confuse administrators.
Secure Token Storage: Never commit your Telegram Bot Token to your version control system. Use environment variables (.env files) to load the token dynamically at runtime.

For more advanced integrations, such as handling deep linking or processing incoming bot updates, refer to the official documentation at https://botservice.biz/telegram-bot-api.

Need assistance building custom Telegram integrations, webhooks, or secure authentication portals? BotCreator — studio that ships Telegram bots / Mini Apps.

Don't trust Laravel's default HTTP client for Telegram webhooks: build a thin wrapper with idempotency

Serhii — Mon, 05 Oct 2026 16:05:50 +0000

Telegram bots that receive updates via webhook need to be both secure and idempotent. A lead‑generation Mini App, for example, sends a JSON payload with the user’s contact details to your Laravel endpoint. If you accept the request blindly, an attacker can replay the same update or forge a request that looks like it came from Telegram, creating duplicate leads or injecting bogus data. Laravel’s built‑in HTTP facade hides the raw response from the Bot API, making it easy to miss a failed ok:false reply and silently drop messages.

This guide walks through a complete, copy‑pasteable implementation: registering a webhook with a secret token, verifying the request, storing the update_id to guarantee exactly‑once processing, and sending outgoing messages through a minimal HTTP client that checks Telegram’s ok field. Each section first shows what breaks when you skip a step, then provides the fix.

1. Register the webhook and protect it with a secret token

If you register a webhook without the secret_token parameter, Telegram will still POST updates to your URL, but anyone who knows the endpoint can send arbitrary JSON. Your controller would treat that payload as a legitimate Update, potentially triggering business logic with fake data.

Failing path – routes/webhook.php without secret verification:

// routes/webhook.php
use Illuminate\Support\Facades\Route;

Route::post('/telegram/webhook', function (\Illuminate\Http\Request $request) {
    // No verification – assumes request came from Telegram
    $update = $request->json()->all();
    // …process $update
    return response('', 204);
});

An attacker could POST {"update_id":999999999,"message":{"chat":{"id":123},"text":"/start"}} and your Laravel app would act on it.

Fix – create a middleware that checks the X-Telegram-Bot-Api-Secret-Token header against the value you gave Telegram when calling setWebhook.

First, store the secret in .env:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_WEBHOOK_SECRET=super-secret-webhook-token

Then publish a config file (optional) or read directly from env.

Create the middleware:

php artisan make:middleware VerifyTelegramSecret

// app/Http/Middleware/VerifyTelegramSecret.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Exception\BadRequestException;

class VerifyTelegramSecret
{
    public function handle(Request $request, Closure $next)
    {
        $signature = $request->header('X-Telegram-Bot-Api-Secret-Token');
        $expected  = config('telegram.webhook_secret');

        if ($signature !== $expected) {
            throw new BadRequestException('Invalid Telegram secret token');
        }

        return $next($request);
    }
}

protected $routeMiddleware = [
    // …
    'telegram.secret' => \App\Http\Middleware\VerifyTelegramSecret::class,
];

Finally, protect the route:

// routes/webhook.php
Route::post('/telegram/webhook', function (\Illuminate\Http\Request $request) {
    $update = $request->json()->all();
    // …process $update
    return response('', 204);
})->middleware('telegram.secret');

When you call setWebhook from the Bot API, include the secret:

curl -F "url=https://example.com/telegram/webhook" \
     -F "secret_token=$TELEGRAM_WEBHOOK_SECRET" \
     "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook"

Now any request lacking the correct header is rejected with 400 before it reaches your controller.

2. Guarantee idempotency by storing processed update_id

Telegram may resend the same update if your webhook returns anything other than 200‑299, or if there is a temporary network glitch. Without deduplication, your job would handle the same payload multiple times, creating duplicate leads or sending the same confirmation message twice.

Failing path – a job that processes the update without checking whether it has already been seen:

// app/Jobs/ProcessTelegramUpdate.php
namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;

class ProcessTelegramUpdate implements ShouldQueue
{
    use Dispatchable, Queueable;

    public $update;

    public function __construct(array $update)
    {
        $this->update = $update;
    }

    public function handle()
    {
        // Assume $this->update['message'] contains a lead
        $lead = $this->update['message'];
        // …store lead in DB, send confirmation, etc.
        // No check – same update_id can be processed again
    }
}

If Telegram retries the webhook three times, you end up with three identical rows in your leads table.

Fix – persist every processed update_id in a fast store (Redis or a dedicated DB table) and skip the job if the id already exists. The check must happen before dispatching the job to avoid queue overhead.

Create a simple table:

CREATE TABLE processed_updates (
    update_id BIGINT PRIMARY KEY,
    processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Add a repository method:

// app/Services/UpdateStore.php
namespace App\Services;

use Illuminate\Support\Facades\DB;

class UpdateStore
{
    public function exists(int $updateId): bool
    {
        return DB::table('processed_updates')->where('update_id', $updateId)->exists();
    }

    public function markAsProcessed(int $updateId): void
    {
        DB::table('processed_updates')->insertOrIgnore([
            'update_id' => $updateId,
        ]);
    }
}

Update the controller to use the store:

// routes/webhook.php
use App\Services\UpdateStore;
use App\Jobs\ProcessTelegramUpdate;

Route::post('/telegram/webhook', function (\Illuminate\Http\Request $request, UpdateStore $store) {
    $payload = $request->json()->all();
    $updateId = $payload['update_id'] ?? null;

    if ($updateId === null) {
        return response('', 400);
    }

    if ($store->exists($updateId)) {
        // Already handled – acknowledge to stop retries
        return response('', 204);
    }

    // Mark as processed *before* dispatching to avoid race conditions
    $store->markAsProcessed($updateId);

    ProcessTelegramUpdate::dispatch($payload);

    return response('', 204);
})->middleware('telegram.secret');

Now even if Telegram retries, the second and third attempts hit the exists check and return 204 immediately, leaving your job to run exactly once.

3. Send outgoing messages via a thin HTTP client that validates Telegram’s response

Laravel’s Http facade is convenient, but it swallows the ok field and only throws on HTTP errors (non‑2xx). Telegram returns HTTP 200 even when the Bot API signals failure (ok:false, error_code, description). If you rely solely on the facade, you might think a message was sent while Telegram actually rejected it because of an invalid chat_id or missing parse mode, leading to silent data loss.

Failing path – using the facade directly:

// app/Services/TelegramClient.php (naive)
namespace App\Services;

use Illuminate\Support\Facades\Http;

class TelegramClient
{
    protected string $token;

    public function __construct()
    {
        $this->token = config('telegram.bot_token');
    }

    public function sendMessage(int $chatId, string $text): void
    {
        $response = Http::post(
            "https://api.telegram.org/bot{$this->token}/sendMessage",
            ['chat_id' => $chatId, 'text' => $text]
        );

        // No check of $response->json()['ok']
        // Errors are ignored
    }
}

If $chatId is wrong, Telegram replies with {"ok":false,"error_code":400,"description":"Bad Request: chat not found"} but your code continues as if everything succeeded.

Fix – wrap the raw request, decode JSON, verify ok, and throw a domain‑specific exception on failure. Keep the client dependency‑free so you can swap it for a mock in tests.

// app/Services/TelegramClient.php
namespace App\Services;

use RuntimeException;

class TelegramClient
{
    protected string $token;
    protected string $apiUrl;

    public function __construct()
    {
        $this->token = config('telegram.bot_token');
        $this->apiUrl = "https://api.telegram.org/bot{$this->token}";
    }

    /**
     * @throws RuntimeException when Telegram returns ok:false
     */
    public function request(string $method, array $params = []): array
    {
        $url = $this->apiUrl . '/' . $method;

        // Use Laravel's Http factory but inspect the raw response
        $response = Http::asForm()->post($url, $params);

        $status = $response->status();
        if ($status < 200 || $status >= 300) {
            throw new RuntimeException("HTTP {$status} from Telegram API");
        }

        $data = $response->json();
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new RuntimeException('Invalid JSON from Telegram');
        }

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

        return $data['result'] ?? [];
    }

    public function sendMessage(int $chatId, string $text): void
    {
        $this->request('sendMessage', [
            'chat_id' => $chatId,
            'text'    => $text,
            'parse_mode' => 'HTML', // example
        ]);
    }
}

Now any API error bubbles up as an exception, which you can catch in your job and decide whether to retry, dead‑letter, or alert an operator.

4. Queue the job and handle failures gracefully

Processing a lead may involve external APIs (CRM, email service) that are slower than the webhook timeout. By dispatching ProcessTelegramUpdate to a queue, you acknowledge the webhook quickly (204) and let the worker run the business logic.

If the job fails, Laravel will retry it according to your queue configuration. Because we already marked the update_id as processed, a retry would otherwise skip the work entirely. To allow retries while still preventing duplicate side‑effects, we store a processing flag rather than a final flag, or we make the job itself idempotent (e.g., using a unique constraint on the leads table).

A simple approach: add a processed_at column that is set only after the job succeeds. The controller marks the update as seen (to stop Telegram retries) but leaves processed_at NULL. The job, upon successful completion, sets the timestamp. If the job fails, the row remains with processed_at NULL, and a later retry will find the row and attempt again.

Adjust the store:

// app/Services/UpdateStore.php
public function markAsSeen(int $updateId): void
{
    DB::table('processed_updates')->updateOrInsert([
        'update_id' => $updateId,
    ], ['processed_at' => null]);
}

public function markAsSuccessful(int $updateId): void
{
    DB::table('processed_updates')
        ->where('update_id', $updateId)
        ->update(['processed_at' => now()]);
}

public function needsProcessing(int $updateId): bool
{
    $row = DB::table('processed_updates')
        ->where('update_id', $updateId)
        ->first();

    return !$row || !$row->processed_at;
}

Controller:

Route::post('/telegram/webhook', function (\Illuminate\Http\Request $request, UpdateStore $store) {
    $payload = $request->json()->all();
    $updateId = $payload['update_id'] ?? null;

    if ($updateId === null || !$store->needsProcessing($updateId)) {
        return response('', 204);
    }

    $store->markAsSeen($updateId);
    ProcessTelegramUpdate::dispatch($payload);

    return response('', 204);
})->middleware('telegram.secret');

Job:

// app/Jobs/ProcessTelegramUpdate.php
public function handle(UpdateStore $store, TelegramClient $telegram)
{
    $update = $this->update;
    $message = $update['message'] ?? null;
    if (!$message || !isset($message['chat']['id'])) {
        return; // nothing to do
    }

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

    // Example: store a lead
    \App\Models\Lead::create([
        'telegram_id' => $chatId,
        'payload'     => json_encode($update),
        'received_at' => now(),
    ]);

    // Send confirmation
    $telegram->sendMessage($chatId, "<b>Thanks!</b> We’ve received your request.");

    // Mark update as successfully processed
    $store->markAsSuccessful($update['update_id']);
}

With this pattern:

Telegram’s retries are stopped early by the needsProcessing check.
If the worker crashes after storing the lead but before sending the confirmation, the row still lacks processed_at, so the next retry will attempt the confirmation again.
Duplicate leads are prevented by a unique index on telegram_id + a hash of the payload, or by relying on the processed_at guard.

Production notes

Expiry and replay attacks – Telegram includes an auth_date field only in Login Widget and Mini App initData; webhook updates do not. Nevertheless, always reject updates that are older than a few minutes if you ever use start payloads for deep links, because a malicious actor could replay an old deep‑link to trigger stale state.
MainButton timing – If you later build a Mini App that shows a MainButton, never enable it before receiving the WebApp.ready event from the Telegram WebApp SDK. Doing so causes the button to be invisible or to trigger errors in older clients.
Idempotency storage – Choose a store with low latency and atomic operations (Redis SET NX EX or a DB table with a primary key). Avoid in‑memory arrays; they disappear on worker restart and break the guarantee.
Monitoring – Log every thrown exception from TelegramClient and set up an alert on a rising rate of ok:false responses. This catches mis‑configured chat_ids or token issues early.

By combining a secret‑token‑protected route, an idempotency layer that persists update_id, and a thin HTTP client that validates Telegram’s ok field, you obtain a webhook handler that is both secure against spoofing and resilient to network glitches. The lead‑generation Mini App can now safely forward user data to your Laravel backend, confident that each update is processed exactly once and that any failure to contact the Bot API is surfaced rather than silently ignored.

BotCreator

Optional further reading:

Secure and Idempotent Telegram Webhook Handler in Pure PHP

Serhii — Mon, 05 Oct 2026 07:00:43 +0000

When building a Telegram bot for production—such as a lead capture system, an e-commerce storefront, or a booking assistant—handling incoming updates reliably is critical. If you simply expose a public PHP script that processes payloads on the fly, your application is vulnerable to two severe issues.

First, because your webhook URL is public, anyone who discovers it can send forged payloads to simulate actions, bypass authorization, or inject malicious data. Second, Telegram expects your server to acknowledge every webhook request with an HTTP 200 OK status within a strict timeout window (typically 5 seconds). If your server experiences a brief network hiccup, database lock, or slow API call, Telegram will retry sending the exact same update. Without idempotency, your bot will process the same action multiple times, leading to duplicate orders, double-posted messages, or corrupted application state.

This tutorial walks through building a secure, production-ready webhook handler in pure PHP. You will implement a secure registration script, verify incoming payloads using a secret token, enforce idempotency using a database, and respond to Telegram instantly to prevent retry loops.

Registering the Webhook with a Secret Token

To prevent unauthorized actors from sending fake updates to your webhook, you must use a secret token. When registering your webhook with the Telegram Bot API, you can pass a secret_token parameter containing an alphanumeric string (1 to 256 characters, including underscores and hyphens). Telegram will then include this token in every incoming request within the X-Telegram-Bot-Api-Secret-Token header.

Do not hardcode your bot token or your secret token. Instead, load them from your environment variables or a secure configuration file. Below is a robust registration script that uses PHP's cURL extension to register your webhook securely. It checks the HTTP status, verifies that the JSON response is valid, and handles potential API errors.

<?php

declare(strict_types=1);

// register.php

$botToken = getenv('TELEGRAM_BOT_TOKEN');
$webhookUrl = getenv('TELEGRAM_WEBHOOK_URL');
$secretToken = getenv('TELEGRAM_SECRET_TOKEN');

if (!$botToken || !$webhookUrl || !$secretToken) {
    fwrite(STDERR, "Error: Missing required environment variables.\n");
    exit(1);
}

$apiUrl = sprintf('https://api.telegram.org/bot%s/setWebhook', $botToken);
$payload = [
    'url' => $webhookUrl,
    'secret_token' => $secretToken,
    'allowed_updates' => ['message', 'callback_query']
];

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

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

if (curl_errno($ch)) {
    $errorMsg = curl_error($ch);
    curl_close($ch);
    fwrite(STDERR, sprintf("cURL Error: %s\n", $errorMsg));
    exit(1);
}

curl_close($ch);

if ($httpCode !== 200) {
    fwrite(STDERR, sprintf("HTTP Error: Received status code %d\n", $httpCode));
    exit(1);
}

$data = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    fwrite(STDERR, "Error: Failed to parse Telegram API response as JSON.\n");
    exit(1);
}

if (!isset($data['ok']) || $data['ok'] !== true) {
    $description = $data['description'] ?? 'Unknown error';
    fwrite(STDERR, sprintf("Telegram API Error: %s\n", $description));
    exit(1);
}

echo "Webhook successfully registered!\n";

Run this script once from your command line to configure your webhook. If the registration succeeds, Telegram will route all future updates to your specified URL, appending your secret token to the headers of every request.

Verifying the Secret Token and Reading the Payload

When an update arrives at your webhook endpoint, your first line of defense is verifying the X-Telegram-Bot-Api-Secret-Token header. If the header is missing or does not match your expected secret, you must terminate the request immediately with an HTTP 403 Forbidden status.

Depending on your web server configuration (Nginx, Apache, or PHP-FPM), the helper function getallheaders() might not be available. To ensure maximum compatibility across different PHP environments, read the header directly from the $_SERVER superglobal. In PHP, custom HTTP headers are normalized to uppercase, prefixed with HTTP_, and hyphens are replaced with underscores.

Here is how to safely read the raw input stream and verify the secret token:

<?php

declare(strict_types=1);

// webhook.php

$expectedSecret = getenv('TELEGRAM_SECRET_TOKEN');

// Retrieve the secret token from the request headers
$providedSecret = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? null;

if (!$expectedSecret || $providedSecret !== $expectedSecret) {
    http_response_code(403);
    echo "Forbidden: Invalid or missing secret token.";
    exit;
}

// Read the raw input stream
$rawInput = file_get_contents('php://input');
if (empty($rawInput)) {
    http_response_code(400);
    echo "Bad Request: Empty payload.";
    exit;
}

$update = json_decode($rawInput, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    echo "Bad Request: Invalid JSON.";
    exit;
}

// The payload is verified and parsed successfully

By rejecting unauthorized requests before parsing the JSON or querying your database, you protect your application from denial-of-service attempts and unauthorized payload injection.

Ensuring Idempotency with update_id

Every update sent by Telegram contains a unique, sequential integer called update_id. If Telegram does not receive a successful HTTP response from your server, it will retry sending the exact same update with the same update_id at regular intervals.

To prevent duplicate processing, you must track processed update_id values in a persistent storage layer. A relational database table with a unique constraint is the most reliable way to handle this. If a second request with the same update_id arrives, your database will reject the insert, allowing you to catch the exception, stop processing, and return a fast 200 OK to Telegram.

First, create a dedicated table in your database to track processed updates:

CREATE TABLE processed_updates (
    update_id BIGINT UNSIGNED PRIMARY KEY,
    processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB;

Next, implement the database check in your PHP webhook handler. Wrap the insertion in a try-catch block. If the insert fails due to a duplicate key violation (SQLSTATE 23000), it means your server has already received or is currently processing this update. You must exit immediately with a 200 OK status so Telegram stops retrying.

<?php

// Database connection configuration
$dbHost = getenv('DB_HOST') ?: '127.0.0.1';
$dbName = getenv('DB_NAME');
$dbUser = getenv('DB_USER');
$dbPass = getenv('DB_PASS');

try {
    $pdo = new PDO(
        "mysql:host={$dbHost};dbname={$dbName};charset=utf8mb4",
        $dbUser,
        $dbPass,
        [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::ATTR_EMULATE_PREPARES => false,
        ]
    );
} catch (PDOException $e) {
    // If the database is down, return a 500 so Telegram retries later
    http_response_code(500);
    error_log("Database connection failed: " . $e->getMessage());
    exit;
}

$updateId = $update['update_id'] ?? null;
if (!$updateId) {
    http_response_code(400);
    echo "Bad Request: Missing update_id.";
    exit;
}

try {
    // Attempt to register the update_id before performing any business logic
    $stmt = $pdo->prepare("INSERT INTO processed_updates (update_id) VALUES (:update_id)");
    $stmt->execute([':update_id' => $updateId]);
} catch (PDOException $e) {
    // SQLSTATE 23000 represents an integrity constraint violation (duplicate key)
    if ($e->getCode() === '23000') {
        http_response_code(200);
        echo "OK: Update already processed.";
        exit;
    }

    // For other database errors, fail with a 500 to trigger a retry
    http_response_code(500);
    error_log("Database error during idempotency check: " . $e->getMessage());
    exit;
}

// Proceed with your business logic safely

Using this pattern, if your webhook takes longer than 5 seconds to run and Telegram retries, the concurrent retry request will hit the database, detect the duplicate update_id, and terminate cleanly with a 200 OK without executing your business logic twice.

Production Notes and Optimization

To run a high-traffic Telegram bot reliably, keep the following architectural practices in mind:

1. Fast Response with `fastcgi_finish_request()`

If your bot needs to perform heavy tasks (such as calling external APIs, generating images, or sending emails), you should close the HTTP connection to Telegram immediately after verifying the update and saving the update_id, but before executing the slow tasks.

If you are running PHP-FPM, you can use the fastcgi_finish_request() function. This sends the HTTP response headers and body back to Telegram and closes the connection, while allowing the PHP process to continue running in the background.

// Send response to Telegram
http_response_code(200);
echo "OK";

// Close connection, but keep executing the script
if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

// Perform long-running operations here
// (e.g., call external APIs, send messages back to Telegram)

2. Database Cleanup

Because Telegram update_id values are sequential and unique, you do not need to keep them in your database forever. A table with millions of rows will slow down index lookups. Set up a daily cron job to delete records older than 24 or 48 hours:

DELETE FROM processed_updates WHERE processed_at < NOW() - INTERVAL 2 DAY;

3. Graceful Error Handling

Never allow PHP to output raw errors or stack traces to the output stream in production (display_errors = Off in your php.ini). If an unhandled exception occurs, catch it, log it to your server logs, and return an appropriate HTTP status code. If the error is transient (like a third-party API timeout), return a 500 Internal Server Error so Telegram retries the update. If the error is permanent (like a malformed payload), return a 200 OK to discard the broken update and prevent infinite retry loops.

Implementing these security and reliability patterns ensures your PHP bot remains stable under heavy load and resilient against malicious traffic. For more details on managing incoming payloads and configuring webhook parameters, refer to the official documentation at https://botservice.biz/telegram-bot-api.

If you need professional assistance architecting, securing, or scaling your Telegram integration, reach out to BotCreator — studio that ships Telegram bots / Mini Apps.

Long-Polling Setup for Telegram Mini Apps in PHP — Offset, Timeout, and Webhook Strategy

Serhii — Sun, 04 Oct 2026 16:02:35 +0000

Why Long Polling Matters for Local Development

When developing a Telegram bot locally, you need a reliable way to receive updates without being overwhelmed by every single message. Telegram's getUpdates method supports long polling, where your server waits for new messages instead of constantly polling the client. This pattern is essential because:

Real-time responsiveness — users see new messages instantly.
Resource efficiency — you don’t waste bandwidth asking repeatedly.
Off-by-one errors — forgetting to track processed messages leads to duplicates or missed updates.

However, long polling introduces pitfalls around offset tracking, timeout handling, and webhook vs. polling decisions. Skipping any of these steps causes subtle bugs: duplicate messages, infinite loops, or crashes when the bot receives more updates than expected.

Below is a complete walkthrough that takes you from initial setup through production-ready patterns, using PHP.

1. Core Setup — Configuring getUpdates with Long Polling

The first thing you need is a working endpoint that exposes /webhook (or /api/updates) to Telegram. For local development, you typically run a simple PHP script that listens on port 5000 (or any free port).

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

use GuzzleHttp\HttpClient;
use GuzzleHttp\Exception\GuzzleException;

// Configuration — keep tokens outside the repo
$botToken = getenv('TELEGRAM_BOT_TOKEN');
$webhookUrl = 'http://localhost:5000/webhook';

// Fetch updates with long polling
$client = new HttpClient();
$response = $client->post($webhookUrl, [
    'headers' => ['Content-Type' => 'application/json'],
]);

$json = json_decode($response->getBody()->getContents(), true);

if ($json['ok'] === false) {
    // Server rejected the request — log and retry later
    error_log('Telegram returned: ' . $json['error']);
}

// Extract the latest message ID and the next offset
$messageId = $json['result']['message']['id'] ?? null;
$offset   = $json['result']['update_offset'] ?? 0;

// Process the message...
echo "Received message ID: $messageId, offset: $offset\n";

// After processing, store the offset so we don’t reprocess the same batch
storeOffset($offset);

Key points in the setup

Endpoint availability — Telegram only accepts requests sent from your own IP. Running on localhost or a private network avoids this restriction.
HTTP method — GET is used for getUpdates, but the response includes a result object describing the batch of messages found since the last offset.
Error checking — Always verify $json['ok']. A false value means Telegram detected something wrong (e.g., invalid token, rate limit, or malformed payload).

If you skip proper error handling here, your bot may silently stop receiving updates, leaving you unaware of failures.

2. Offset Tracking — Avoiding Duplicates and Gaps

The offset field tells you how many messages were already delivered to your bot since the last poll. By storing and incrementing this value, you guarantee exactly-once delivery per batch.

Here’s a robust way to persist the offset in a lightweight way (using SQLite for simplicity):

<?php
/**
 * Store the next offset after processing a batch of messages.
 */
function storeOffset(int $offset): void {
    try {
        $pdo = new PDO('sqlite:/tmp/telegram.db', []);
        $stmt = $pdo->prepare('INSERT INTO last_offset (offset) VALUES (?) ON CONFLICT DO NOTHING');
        $stmt->execute([$offset]);
        // If the insert succeeded, the row was newly created (no conflict)
        if ($pdo->rowCount() > 0) {
            echo "Stored new offset: $offset\n";
        } else {
            // Offset already exists — nothing to do
            echo "Offset already recorded: $offset\n";
        }
    } catch (\PDOException $e) {
        // Log but don’t crash — the offset table may be stale anyway
        error_log("Failed to store offset: " . $e->getMessage());
    }
}

Why persistence matters

Without persistent storage, each restart would re-process everything from the beginning. That’s fine for a quick test, but in a real deployment you might have restarts, load balancers, or container resets. Storing the offset gives you idempotent behavior across restarts.

Common mistake: reprocessing old batches

If you forget to increment the offset after handling a batch, Telegram will deliver the same messages again. You’ll end up with duplicate notifications in your chat history and potentially double-counted events in your analytics.

Another trap: stale offset values

If your offset gets out of sync (e.g., due to a bug that doesn’t save it), you could miss messages. Always pair the offset logic with a health check that verifies the current offset matches what Telegram reports.

3. Timeout and Retry Logic — Don’t Block Forever

Long polling has a default timeout of 30 seconds (configurable per Telegram API docs). If no new messages arrive within that window, Telegram returns a 200 OK with an empty result set. Your script should respect this:

<?php
const LONG_POLL_TIMEOUT = 30; // seconds

function fetchUpdates(): array {
    $client = new HttpClient();
    $url = getenv('WEBHOOK_URL') ?: 'http://localhost:5000/webhook';

    $response = $client->post($url, []);
    $body = json_decode($response->getBody()->getContents(), true);

    if (!isset($body['ok']) || !is_array($body['result'])) {
        throw new RuntimeException('Invalid Telegram response');
    }

    return $body['result'];
}

What happens if you ignore the timeout?

If you keep polling indefinitely without a timeout, your script will hang forever. More insidiously, if you set a very short timeout (e.g., 1 second) you risk missing bursts of activity. The sweet spot for local development is 15–20 seconds — fast enough to react to most conversations, slow enough to avoid overwhelming the network.

Retry strategy

When Telegram returns an error (non‑ok), you should log it and either:

Retry immediately if the error is transient (rate limits, temporary connectivity issues).
Back off exponentially if the error persists (e.g., 429 Too Many Requests).

<?php
const MAX_RETRIES = 3;
function pollWithRetry(): array {
    $attempt = 0;
    while ($attempt <= MAX_RETRIES) {
        $batch = fetchUpdates();
        if (empty($batch)) continue; // No new messages

        processBatch($batch);
        storeOffset(getLastOffset()); // assume batch size == offset delta
        break; // Success — exit retry loop
    }
    return $batch;
}

4. When to Use Webhook Instead of Long Polling

For production deployments behind a public HTTPS endpoint, webhooks are generally preferred over long polling. Here’s the trade-off:

Aspect	Long Polling	Webhook
Setup complexity	Simple — runs on localhost	Requires HTTPS endpoint, SSL certs, and a public URL
Reliability	Works even if the bot isn’t reachable	Depends on network reachability and uptime
Duplicate handling	Manual offset management needed	Telegram handles deduplication via `callback_query_id`
Maintenance	Stateless, easy to debug	Need to handle incoming POST requests, validate signatures

For local development, long polling is perfectly adequate. You can simulate a webhook by having your PHP script act as both the listener and the handler. Once you’re confident the flow works, you can transition to webhooks by replacing the fetchUpdates() call with a route that listens for POST /webhook.

Hybrid approach

Many teams start with long polling during development and switch to webhooks once their infrastructure is ready. The transition is smooth: keep the same offset logic, just change the entry point from getUpdates to a route handler.

5. Production Notes — Expiry, Replay, and MainButton Timing

Even with perfect local setup, moving to production requires attention to several edge cases:

Update expiry — Telegram keeps updates for a limited time. If your bot stops responding, older updates may be discarded. Implement a heartbeat mechanism (periodic pings) to keep your presence alive.
Replay protection — If you ever switch back to webhooks, ensure you don’t accidentally replay old messages. Webhook responses include a callback_query_id that uniquely identifies each event; store this alongside the message content.
MainButton timing — The MainButton action appears in the chat after the bot sends a message. If your bot sends a message and then tries to read a reply before the button is visible, you’ll get answer_callback_query errors. Always wait until the bot has received a confirmation (e.g., via getUpdates with reply_to_message_id filtering) before interacting with inline keyboards.

Example: Safe MainButton Flow

<?php
// Assume $message contains the text and a reference to the main button
$buttonId = $message['from']['reply_to_message_id']; // or extract from payload

// Send the button
$payload = json_encode([
    'text' => 'Choose option',
    'inline_keyboard' => [
        ['id' => 'option_1', 'label' => 'Yes'],
        ['id' => 'option_2', 'label' => 'No'],
    ],
]);

$client->post(
    $webhookUrl,
    ['method' => 'POST', 'header' => ['Content-Type' => 'application/json'], 'body' => $payload]
);

// Wait for the button press (poll briefly)
$wait = waitForReply($messageId, 10); // max 10 seconds
if ($wait > 0) {
    $callback = fetchUpdates();
    foreach ($callback['result'] as $msg) {
        if ($msg['type'] === 'callback_query' && $msg['data'] === $buttonId) {
            // User pressed a button — handle accordingly
            break;
        }
    }
}

This pattern ensures you don’t race against the UI rendering cycle.

6. Putting It All Together — A Complete Local Dev Loop

Here’s the minimal but complete workflow you can drop into a project:

Start the webhook server

   php --daemon webhook-server.php

Run the long-polling handler

   php longpoll-loop.php

Persist offsets in a lightweight DB (SQLite works for single-instance setups).
Test with a simple command — e.g., /start to trigger a message, then watch the offset increase.
Add a health endpoint (/status) that returns the current offset so you can monitor the bot from another terminal.

By following these steps, you eliminate the most common pitfalls: duplicate messages, lost updates, and silent failures. The combination of offset tracking, proper timeout handling, and explicit error logging makes your local development loop as reliable as the production version.

Final Thoughts

Long polling is a powerful pattern for Telegram bot development, but it demands discipline around state management (offsets), error handling (timeouts, retries), and the choice between polling and webhooks. When done right, it provides a responsive experience for users while keeping your backend clean and debuggable.

If you find yourself needing help shipping polished Telegram bots and Mini Apps, consider the tools at BotCreator — they ship production-ready solutions built on top of the official Bot API.

BotCreator

Build a Vue 3 Mini App Storefront with Pinia and Telegram Native Invoices

Serhii — Sun, 04 Oct 2026 08:11:28 +0000

Building an e-commerce storefront inside a Telegram Mini App provides a seamless user experience, but it introduces state management and payment flow challenges distinct from regular web applications. When users navigate through a Vue 3 catalog inside Telegram's embedded WebApp webview, they expect native UI integration. Using custom HTML checkout buttons instead of Telegram's native MainButton breaks this native feeling, while relying on unsynchronized in-memory state leads to frustrating cart resets whenever the webview reloads or closes.

A naive approach often places item prices and cart totals directly inside client-side components and submits these amounts to a payment provider. If your frontend submits the final price calculated in JavaScript to generate a payment invoice, malicious users can open Telegram WebApp developer tools, edit the JavaScript state, and purchase items for cents.

To build a production-ready catalog in Vue 3, you need a robust persistent cart using Pinia, seamless two-way binding with Telegram's native MainButton, and a backend-driven checkout pipeline that issues Telegram Bot API invoice links after verifying item prices on the server.

State Management: Building a Persistent Pinia Store

The first point of failure in a Mini App catalog is cart state volatile behavior. When users minimize the Mini App, answer a chat message, or receive an incoming call, the Telegram client may discard or refresh the webview instance. If your cart relies solely on standard Vue ref state, the cart wipes clean upon restore.

To prevent cart state loss, we implement a Pinia store that automatically serializes cart changes to localStorage. We must also structure the store to track item quantities and recalculate item totals reactively.

Create your catalog cart store inside src/stores/cart.js or src/stores/cart.ts:

import { defineStore } from 'pinia';
import { ref, computed, watch } from 'vue';

export interface CartItem {
  id: string;
  title: string;
  price: number; // in minor units, e.g., cents or smallest currency unit
  quantity: number;
}

export const useCartStore = defineStore('cart', () => {
  const items = ref<CartItem[]>([]);

  // Hydrate cart from localStorage on initialization
  const savedCart = localStorage.getItem('telegram_cart_items');
  if (savedCart) {
    try {
      items.value = JSON.parse(savedCart);
    } catch (e) {
      console.error('Failed to parse cached cart items:', e);
      localStorage.removeItem('telegram_cart_items');
    }
  }

  // Persist changes to localStorage automatically
  watch(
    items,
    (newItems) => {
      localStorage.setItem('telegram_cart_items', JSON.stringify(newItems));
    },
    { deep: true }
  );

  const totalAmount = computed(() => {
    return items.value.reduce((sum, item) => sum + item.price * item.quantity, 0);
  });

  const totalCount = computed(() => {
    return items.value.reduce((sum, item) => sum + item.quantity, 0);
  });

  function addItem(product: { id: string; title: string; price: number }) {
    const existing = items.value.find((i) => i.id === product.id);
    if (existing) {
      existing.quantity += 1;
    } else {
      items.value.push({ ...product, quantity: 1 });
    }
  }

  function removeItem(productId: string) {
    const index = items.value.findIndex((i) => i.id === productId);
    if (index !== -1) {
      if (items.value[index].quantity > 1) {
        items.value[index].quantity -= 1;
      } else {
        items.value.splice(index, 1);
      }
    }
  }

  function clearCart() {
    items.value = [];
    localStorage.removeItem('telegram_cart_items');
  }

  return {
    items,
    totalAmount,
    totalCount,
    addItem,
    removeItem,
    clearCart,
  };
});

Using watch with { deep: true } ensures that updating an item's quantity syncs immediately to local storage. By storing prices in minor currency units (such as 1500 for $15.00 or 1500 stars/cents), you avoid floating-point rounding errors when calculating cart subtotals.

Syncing Vue Reactive State with Telegram MainButton

Telegram provides a native MainButton fixed to the bottom of the WebApp viewport. Rendering a custom fixed position HTML button inside your Vue template creates visual inconsistency, conflicts with soft keyboard safe areas, and overlaps Telegram's native footer interface.

However, synchronizing Vue's reactive state with window.Telegram.WebApp.MainButton presents another common trap: event handler accumulation. If you register click listeners on MainButton inside Vue lifecycle hooks without removing them on unmount or reactive changes, clicking the button once will trigger multiple duplicate order submissions.

To encapsulate this cleanly, build a custom Vue composable that watches Pinia store changes and safely handles MainButton lifecycle events.

Create src/composables/useTelegramMainButton.ts:

import { watch, onUnmounted } from 'vue';
import { useCartStore } from '../stores/cart';

export function useTelegramMainButton(onCheckoutTriggered: () => void) {
  const cartStore = useCartStore();
  const tg = window.Telegram?.WebApp;

  if (!tg) {
    return;
  }

  const handleMainButtonClick = () => {
    onCheckoutTriggered();
  };

  // Ensure button is initialized
  tg.MainButton.onClick(handleMainButtonClick);

  // Watch cart changes and update Telegram native button UI
  watch(
    [() => cartStore.totalAmount, () => cartStore.totalCount],
    ([newAmount, newCount]) => {
      if (newCount > 0) {
        const formattedPrice = (newAmount / 100).toFixed(2);
        tg.MainButton.setText(`VIEW CART ($${formattedPrice})`);
        tg.MainButton.enable();
        tg.MainButton.show();
      } else {
        tg.MainButton.hide();
      }
    },
    { immediate: true }
  );

  // Clean up listener to prevent duplicate clicks on re-render
  onUnmounted(() => {
    tg.MainButton.offClick(handleMainButtonClick);
    tg.MainButton.hide();
  });

  function showLoading(text = 'Processing...') {
    tg.MainButton.setText(text);
    tg.MainButton.showProgress();
    tg.MainButton.disable();
  }

  function hideLoading() {
    tg.MainButton.hideProgress();
    tg.MainButton.enable();
  }

  return {
    showLoading,
    hideLoading,
  };
}

This composable ensures that when the catalog cart is empty, the native button vanishes automatically. When items are added, the button smoothly animates into place with the calculated total amount, mimicking the feel of native iOS and Android apps.

Secure Checkout: Backend Invoice Generation

Never trust the frontend to provide final prices or product amounts. A complete checkout pipeline must send only item identifiers and quantities to a secure backend route. The backend must query the database, compute the exact total, generate a Telegram payment link using the official Bot API method createInvoiceLink, and return that URL to the Vue client.

Here is a Node.js Express endpoint demonstrating secure invoice creation:

import express from 'express';
import fetch from 'node-fetch';

const app = express();
app.use(express.json());

const BOT_TOKEN = process.env.BOT_TOKEN;
const PAYMENT_PROVIDER_TOKEN = process.env.PAYMENT_PROVIDER_TOKEN; // Empty for Telegram Stars

// Mock server database
const PRODUCT_DATABASE = {
  'prod_1': { title: 'Premium Coffee Beans', price: 1500 }, // $15.00
  'prod_2': { title: 'Ceramic Mug', price: 1200 },          // $12.00
};

app.post('/api/checkout', async (req, res) => {
  const { initData, cart } = req.body;

  // IMPORTANT: Verify initData HMAC signature in production here!
  if (!initData) {
    return res.status(401).json({ error: 'Unauthorized request' });
  }

  // Calculate prices strictly from backend database
  const invoicePrices = [];
  for (const item of cart) {
    const dbProduct = PRODUCT_DATABASE[item.id];
    if (!dbProduct) {
      return res.status(400).json({ error: `Invalid product ID: ${item.id}` });
    }
    invoicePrices.push({
      label: `${dbProduct.title} x${item.quantity}`,
      amount: dbProduct.price * item.quantity,
    });
  }

  if (invoicePrices.length === 0) {
    return res.status(400).json({ error: 'Cart is empty' });
  }

  try {
    const response = await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/createInvoiceLink`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        title: 'Store Checkout',
        description: 'Order from Mini App Storefront',
        payload: JSON.stringify({ order_id: Date.now() }), // Unique tracking payload
        provider_token: PAYMENT_PROVIDER_TOKEN,
        currency: 'USD',
        prices: invoicePrices,
      }),
    });

    const data = await response.json();

    if (!data.ok) {
      console.error('Telegram Bot API Error:', data);
      return res.status(500).json({ error: 'Failed to generate payment invoice' });
    }

    // Return generated invoice URL to frontend
    res.json({ invoiceUrl: data.result });
  } catch (error) {
    console.error('Server error during checkout:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

This pattern ensures product pricing rules remain completely hidden from the client layer. If a user modifies item quantities or prices in local memory, the server checks product IDs against PRODUCT_DATABASE and ignores client-side pricing overrides entirely.

Invoking Native Payments in Vue Component

Now we connect the Vue storefront view to our backend and open Telegram's payment webview using window.Telegram.WebApp.openInvoice.

Create src/views/CatalogView.vue:

<template>
  <div class="catalog">
    <h1>Products</h1>
    <div class="product-grid">
      <div v-for="product in products" :key="product.id" class="product-card">
        <h3>{{ product.title }}</h3>
        <p>${{ (product.price / 100).toFixed(2) }}</p>
        <div class="actions">
          <button @click="cartStore.removeItem(product.id)">-</button>
          <span>{{ getItemQuantity(product.id) }}</span>
          <button @click="cartStore.addItem(product)">+</button>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useCartStore } from '../stores/cart';
import { useTelegramMainButton } from '../composables/useTelegramMainButton';

const cartStore = useCartStore();

const products = ref([
  { id: 'prod_1', title: 'Premium Coffee Beans', price: 1500 },
  { id: 'prod_2', title: 'Ceramic Mug', price: 1200 },
]);

function getItemQuantity(id: string): number {
  const item = cartStore.items.find((i) => i.id === id);
  return item ? item.quantity : 0;
}

const { showLoading, hideLoading } = useTelegramMainButton(handleCheckout);

async function handleCheckout() {
  const tg = window.Telegram?.WebApp;
  if (!tg) return;

  showLoading('Generating Invoice...');

  try {
    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        initData: tg.initData,
        cart: cartStore.items.map((item) => ({
          id: item.id,
          quantity: item.quantity,
        })),
      }),
    });

    const data = await response.json();

    if (!response.ok || !data.invoiceUrl) {
      throw new Error(data.error || 'Invoice generation failed');
    }

    hideLoading();

    // Open native Telegram payment UI
    tg.openInvoice(data.invoiceUrl, (status: string) => {
      if (status === 'paid') {
        tg.HapticFeedback.notificationOccurred('success');
        cartStore.clearCart();
        tg.showAlert('Thank you for your purchase!');
      } else if (status === 'failed') {
        tg.HapticFeedback.notificationOccurred('error');
        tg.showAlert('Payment was not completed. Please try again.');
      } else if (status === 'cancelled') {
        // Payment modal closed by user, retain cart
        console.log('Payment modal dismissed by user');
      }
    });
  } catch (err: any) {
    hideLoading();
    tg.showAlert(err.message || 'An error occurred during checkout');
  }
}
</script>

When tg.openInvoice opens, Telegram suspends the webview focus and overlays a native modal screen for inputting credit card details or paying via Telegram Stars. The callback provides three status codes: paid, cancelled, or failed.

Only clear the Pinia cart inside the paid branch. If the status is cancelled, leaving the cart intact allows users to adjust their item quantities or attempt checkout again without losing their selected items.

Production Checklist & Edge Cases

When shipping your Vue Mini App catalog to real users, keep these operational details in mind:

Calling WebApp.ready() Early: Always invoke window.Telegram.WebApp.ready() inside your root Vue component (App.vue) immediately when mounted. If you delay calling ready(), Telegram shows a loading spinner over your Mini App and may block interaction events on the MainButton.
Parsing Telegram WebApp Theme Variables: Users may switch between Dark Mode and Light Mode while the app is active. Ensure your Vue application binds to CSS custom properties provided by Telegram (var(--tg-theme-bg-color), var(--tg-theme-text-color)) rather than hardcoding static hex colors.
Handling Replay Attacks and Stale Requests: Even though createInvoiceLink creates isolated links, always record the order_id in your backend database and mark it as fulfilled using a Webhook listener for pre_checkout_query and successful_payment. Relying strictly on the frontend openInvoice callback to fullfill orders is insecure because client network connections can drop before the callback executes.
Clearing LocalStorage on Schema Migrations: If you update your product store structure in a future app deployment (e.g., adding variant attributes or changing field names), existing users with old JSON formats stored in localStorage might crash your Vue app. Always wrap JSON.parse() in a try/catch block and clear invalid caches gracefully.

If you need a dedicated team to architect, audit, or scale complex web applications and embedded Telegram solutions, consider reaching out to BotCreator — studio that ships Telegram bots / Mini Apps.

Prevent Duplicate Telegram Bot Actions: Build an Idempotent Webhook Handler in Laravel

Serhii — Sat, 03 Oct 2026 17:03:13 +0000

Imagine running a Telegram-based digital storefront or a booking bot. A user clicks a button to purchase a subscription or confirm a booking. Your server receives the webhook from Telegram, begins processing the payment, and updates your database. However, due to a temporary network hiccup or a slow external API call, your server takes more than five seconds to respond.

Telegram's webhook engine assumes your server failed to receive the payload if it does not get an immediate HTTP 200 OK response. It will retry sending the exact same payload. If your webhook handler runs synchronously and lacks protection, the user is charged twice, or duplicate database records are created.

To build a production-grade Telegram bot, you must solve three critical problems: secure your webhook endpoint from unauthorized requests, respond to Telegram instantly to prevent retries, and ensure that each unique update payload is processed exactly once. This walkthrough demonstrates how to implement a secure, queued, and idempotent Telegram webhook architecture in Laravel using custom middleware, Redis-backed atomic locks, and queued jobs.

Securing the Entry Point with Telegram Secret Tokens

Before processing any payload, you must verify that the incoming request actually originated from Telegram. Anyone who discovers your webhook URL could send spoofed payloads to manipulate your application's state.

Telegram provides a secure verification mechanism: the X-Telegram-Bot-Api-Secret-Token header. When you register your webhook using the setWebhook method, you can pass an arbitrary string as the secret_token. Telegram will then include this token in the header of every single webhook request. If the header is missing or does not match your configured secret, you can immediately reject the request.

First, add your Telegram configuration to your config/services.php file:

return [
    // ... other services
    'telegram' => [
        'bot_token' => env('TELEGRAM_BOT_TOKEN'),
        'secret_token' => env('TELEGRAM_SECRET_TOKEN'),
    ],
];

Next, generate a custom middleware to handle this verification:

php artisan make:middleware VerifyTelegramSecret

Open the newly created middleware file and implement the verification logic. We will compare the incoming header against our configured secret token. To prevent timing attacks, we use PHP's hash_equals function for a constant-time string comparison.

<?php

namespace App\Http\Middleware;

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

class VerifyTelegramSecret
{
    /**
     * Handle an incoming request.
     */
    public function handle(Request $request, Closure $next): Response
    {
        $configuredSecret = config('services.telegram.secret_token');

        // If no secret is configured, block requests by default in production
        if (empty($configuredSecret)) {
            return response()->json(['error' => 'Webhook secret token not configured.'], 500);
        }

        $incomingSecret = $request->header('X-Telegram-Bot-Api-Secret-Token');

        if (!$incomingSecret || !hash_equals($configuredSecret, $incomingSecret)) {
            return response()->json(['error' => 'Unauthorized.'], 403);
        }

        return $next($request);
    }
}

Now, register this middleware in your application. If you are using Laravel 11, you can apply it directly to your routes in routes/api.php or register it in bootstrap/app.php. Let's define the route in routes/api.php and apply our middleware:

<?php

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

Route::post('/telegram/webhook', TelegramWebhookController::class)
    ->middleware(VerifyTelegramSecret::class);

Dispatching to Queues and Ensuring Idempotency with Redis

Once the request passes the security check, we must handle it. To prevent Telegram from timing out and retrying, we must not perform any heavy lifting (such as database writes, external API calls, or sending messages back to Telegram) inside the HTTP request lifecycle. We must dispatch a queued job and return an HTTP 200 OK immediately.

However, simply dispatching a job does not solve the duplication problem. If Telegram retries the request before your server can return 200 OK, or if a network delay causes the same update to be sent twice, your queue will receive duplicate jobs.

To prevent this, we use the unique update_id provided in every Telegram update payload. We can leverage Redis to perform an atomic "set if not exists" (NX) operation. If we successfully store the update_id in Redis, it means this is the first time we are seeing this update. If the key already exists, we discard the request immediately and return 200 OK to tell Telegram we have received it.

Generate the controller:

php artisan make:controller TelegramWebhookController --invokable

Implement the controller logic using Laravel's Redis facade to enforce idempotency:

<?php

namespace App\Http\Controllers;

use App\Jobs\ProcessTelegramUpdate;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Redis;

class TelegramWebhookController
{
    /**
     * Handle the incoming Telegram webhook.
     */
    public function __invoke(Request $request): JsonResponse
    {
        $payload = $request->all();
        $updateId = $payload['update_id'] ?? null;

        if (!$updateId) {
            return response()->json(['error' => 'Invalid payload: missing update_id.'], 400);
        }

        $redisKey = "telegram_update:{$updateId}";

        // Attempt to set the key with a 24-hour (86400 seconds) expiration time.
        // 'NX' ensures the key is only set if it does not already exist.
        $isUnique = Redis::executeRaw([
            'SET',
            $redisKey,
            'processed',
            'EX',
            86400,
            'NX'
        ]);

        if (!$isUnique) {
            Log::info("Duplicate Telegram update ignored.", ['update_id' => $updateId]);
            // Return 200 OK so Telegram stops retrying this specific update
            return response()->json(['status' => 'duplicate_ignored']);
        }

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

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

Handling the Queued Job Safely

Now that the payload is safely validated and deduplicated, we can process it in a queued job. If the job fails due to an external service outage, Laravel's queue worker can retry it. Because we already marked the update_id as processed in Redis during the controller phase, subsequent retries of the same webhook request from Telegram will be ignored, but our internal queue retries will still run safely to completion.

Generate the queued job:

php artisan make:job ProcessTelegramUpdate

Inside the job, we will parse the payload and execute our business logic. For this example, we will handle a basic text message and reply to the user using Laravel's HTTP client. We must also handle potential API errors from Telegram gracefully.

<?php

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\Facades\Http;
use Illuminate\Support\Facades\Log;
use Exception;

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

    /**
     * The number of times the job may be attempted.
     */
    public int $tries = 3;

    /**
     * The number of seconds to wait before retrying the job.
     */
    public int $backoff = 5;

    /**
     * Create a new job instance.
     */
    public function __construct(protected array $payload)
    {
    }

    /**
     * Execute the job.
     */
    public function handle(): void
    {
        $message = $this->payload['message'] ?? null;
        if (!$message) {
            return;
        }

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

        if (!$chatId || empty($text)) {
            return;
        }

        // Example business logic: Echo back the message
        $replyText = "You said: " . htmlspecialchars($text, ENT_QUOTES, 'UTF-8');

        $this->sendTelegramMessage($chatId, $replyText);
    }

    /**
     * Send a message back to Telegram via the Bot API.
     */
    protected function sendTelegramMessage(int $chatId, string $text): void
    {
        $token = config('services.telegram.bot_token');
        $url = "https://api.telegram.org/bot{$token}/sendMessage";

        $response = Http::timeout(10)->post($url, [
            'chat_id' => $chatId,
            'text' => $text,
            'parse_mode' => 'HTML',
        ]);

        if ($response->failed()) {
            $errorData = $response->json();
            Log::error('Telegram API error', [
                'status' => $response->status(),
                'response' => $errorData,
            ]);

            // If Telegram returns a 429 (Too Many Requests) or a 5xx server error, retry the job
            if ($response->status() === 429 || $response->status() >= 500) {
                throw new Exception("Telegram API failed with status " . $response->status());
            }
        }
    }
}

Production Notes

When deploying this architecture to production, keep the following operational details in mind:

Setting the Webhook Correctly: You must register your webhook with Telegram and provide the secret token. You can do this via a simple curl request. Replace <YOUR_BOT_TOKEN> with your actual bot token, and set the url and secret_token parameters:

   curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
        -H "Content-Type: application/json" \
        -d '{"url": "https://yourdomain.com/api/telegram/webhook", "secret_token": "your_secure_random_secret_token_here"}'

Redis Key Expiration (TTL): In our controller, we set the Redis key expiration to 24 hours (86400 seconds). Telegram does not keep retrying updates for longer than 24 hours. This TTL prevents your Redis instance from growing indefinitely while ensuring that any delayed retries from Telegram are still caught by the deduplication layer.
Queue Worker Configuration: Ensure your queue workers are running continuously in production using a process monitor like Supervisor. If your queue worker stops, updates will pile up in your queue database, but your webhook controller will still return 200 OK to Telegram, preventing Telegram from spamming your server with retries.
Database Transactions: If your job performs database writes, wrap them in a transaction. If the job fails halfway through and retries, you want to ensure that any partial database changes are rolled back before the next attempt runs.

If you need help building reliable, high-performance messaging systems or custom integrations, reach out to BotCreator — studio that ships Telegram bots / Mini Apps. For more details on working with Telegram's official endpoints, consult the documentation at

DEV Community: Serhii

Telegram Mini App shop in Next.js fixing MainButton checkout and iOS viewport

Setting up the Next.js App Router project

Building the product list and cart

Adding MainButton and handling checkout

Creating Telegram invoice via bot API

Desktop vs iOS WebView quirks

Production notes

Stop RAM Exhaustion When Uploading Telegram Media in PHP by Reusing File IDs

Stream Multipart Media Uploads with Raw cURL and Error Handling

Select Between Direct URL Passing and Multipart Binaries

Cache and Reuse file_id to Skip Media Upload Overhead

Production Notes and Edge Case Recovery

1. file_id Scope and Invalidation

2. Timeouts and Network Tuning

3. MIME Type Detection Safety

Exchange Telegram WebApp InitData for Validated JWTs in React and PHP

The Failure Mode: Why Client-Side Auth Collapses

Step 1: Sending Raw initData from React to Your PHP API

Step 2: Verifying the HMAC-SHA256 Signature in PHP

Step 3: Swapping Verified Credentials for a Backend JWT

Step 4: Making Authenticated API Calls in React

Production Security Notes

Prevent Telegram Callback Timeouts and 64-Byte Payload Truncation in PHP

Designing Short Callbacks Under Telegram's 64-Byte Limit

Handling Callback Queries and Silencing Client UI Spinners

Modifying Message UI In-Place with editMessageText

Production Considerations: Race Conditions, Idempotency, and Failures

Concurrent Button Taps (Race Conditions)

Expiry of Historical Message Keys

Network Delays and Webhook Deadlocks

Prevent Unassigned Web Leads: Process Telegram Manager Claim Keyboards in PHP

Step 1: Generating Lead IDs and Persisting Form Submissions

Step 2: Atomic State Processing and Preventing Double-Claims

Step 3: Production Security and Telegram API Failure Cases

1. Telegram 64-Byte Callback Limit Budget

2. Secret Token Authentication

3. Immediate HTTP 200 Responses

Prevent Telegram Broadcast Crashes by Handling 429 Retry-After and Queueing in PHP

The Naive Loop and Why It Fails

Building a Rate-Aware HTTP Client

Designing a Database-Backed Queue and Worker

Production Notes

Webhook Execution Limits

Idempotency and Duplicate Prevention

Safe HTML Formatting

Handling Callback Queries

Stop Spoofed Telegram Logins by Verifying HMAC and Binding IDs in Yii2

The Vulnerability: Why Client-Side Data is a Trap

Step 1: Prepare the Database Migration

Step 2: Implement the Cryptographic Verification Service

Step 3: Integrate with Yii2 Controller

Production Considerations & Edge Cases

Don't trust Laravel's default HTTP client for Telegram webhooks: build a thin wrapper with idempotency

1. Register the webhook and protect it with a secret token

2. Guarantee idempotency by storing processed update_id

3. Send outgoing messages via a thin HTTP client that validates Telegram’s response

4. Queue the job and handle failures gracefully

Production notes

Secure and Idempotent Telegram Webhook Handler in Pure PHP

Registering the Webhook with a Secret Token

Verifying the Secret Token and Reading the Payload

Ensuring Idempotency with update_id

Production Notes and Optimization

1. Fast Response with fastcgi_finish_request()

2. Database Cleanup

3. Graceful Error Handling

Long-Polling Setup for Telegram Mini Apps in PHP — Offset, Timeout, and Webhook Strategy

Why Long Polling Matters for Local Development

1. Core Setup — Configuring getUpdates with Long Polling

Key points in the setup

2. Offset Tracking — Avoiding Duplicates and Gaps

Why persistence matters

Common mistake: reprocessing old batches

Another trap: stale offset values

3. Timeout and Retry Logic — Don’t Block Forever

What happens if you ignore the timeout?

Retry strategy

4. When to Use Webhook Instead of Long Polling

Hybrid approach

1. `file_id` Scope and Invalidation

1. Fast Response with `fastcgi_finish_request()`