Telegram Bot API: ready-to-use code snippets

How it works: Telegram deep links look like t.me/YourBot?start=PAYLOAD, and the bot receives it as /start PAYLOAD; a simple prefix convention (ref_, utm_, referral_) on the payload lets you encode attribution data without any extra API calls.

function parseStartParams(startCommand) {
  const [, param] = startCommand.split(' ')
  if (!param) return { source: 'telegram' }

  // /start ref_telegram_ad
  if (param.startsWith('ref_')) {
    return { source: param.replace('ref_', '') }
  }

  // /start utm_source-google_medium-cpc_campaign-spring
  if (param.startsWith('utm_')) {
    const utm = {}
    param.replace('utm_', '').split('_').forEach((part) => {
      const [key, value] = part.split('-')
      if (key && value) utm[`utm_${key}`] = decodeURIComponent(value)
    })
    return { source: utm.utm_source || 'unknown', medium: utm.utm_medium, campaign: utm.utm_campaign, utm }
  }

  // /start referral_12345
  if (param.startsWith('referral_')) {
    const referrerId = parseInt(param.replace('referral_', ''), 10)
    if (!Number.isNaN(referrerId)) return { source: 'referral', referrerId }
  }

  return { source: param }
}

// Example usage
parseStartParams('/start ref_instagram_bio')
// { source: 'instagram_bio' }
parseStartParams('/start referral_12345')
// { source: 'referral', referrerId: 12345 }

How it works: Telegram inline keyboards have a fixed visual width. When the message above is short, one button per row reads better; when it's long enough that vertical space matters, adjacent short buttons (like "Yes"/"No") get greedily paired into the same row while long ones stay on their own.

const SHORT_CONTENT_THRESHOLD = 35
const SHORT_BUTTON_THRESHOLD = 10

function layoutTelegramButtons(buttons, contentLength) {
  if (buttons.length <= 1) return buttons.map((b) => [b])

  if (contentLength < SHORT_CONTENT_THRESHOLD) {
    return buttons.map((b) => [b])
  }

  const rows = []
  let i = 0
  while (i < buttons.length) {
    const current = buttons[i]
    const next = buttons[i + 1]
    const bothShort = next && current.text.length <= SHORT_BUTTON_THRESHOLD && next.text.length <= SHORT_BUTTON_THRESHOLD

    if (bothShort) {
      rows.push([current, next])
      i += 2
    } else {
      rows.push([current])
      i += 1
    }
  }
  return rows
}

// Example usage — feed straight into Telegram's inline_keyboard
const inline_keyboard = layoutTelegramButtons(
  [{ text: 'Yes', callback_data: 'y' }, { text: 'No', callback_data: 'n' }],
  120
)
// [[{text:'Yes',...}, {text:'No',...}]] — paired into one row

How it works: Telegram requires you to answer every callback_query within 10 seconds, otherwise the user sees an infinite spinner on the button. answerCallbackQuery dismisses it. The optional text shows a pop-up notification (toast or alert).

async function answerCallbackQuery(token, callbackQueryId, options = {}) {
  const url = `https://api.telegram.org/bot${token}/answerCallbackQuery`
  const res = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      callback_query_id: callbackQueryId,
      ...options,
    }),
  })

  if (!res.ok) throw new Error(`Telegram API error: ${res.status}`)
  return res.json()
}

// Example usage — silent answer (just dismiss the spinner)
await answerCallbackQuery(token, query.id)

// With a notification (toast at the bottom, up to 200 characters)
await answerCallbackQuery(token, query.id, {
  text: 'Order confirmed ✅',
  show_alert: false,
})

// As a modal alert
await answerCallbackQuery(token, query.id, {
  text: 'Action unavailable. Please try again later.',
  show_alert: true,
})

How it works: Telegram can send updates of different types, and the from field (user data) lives in different locations. The function walks through all possible paths and returns a normalised object, or null if the update has no user data (e.g. a channel post).

function getUserFromUpdate(update) {
  const from =
    update.message?.from ??
    update.callback_query?.from ??
    update.edited_message?.from ??
    update.inline_query?.from ??
    update.chosen_inline_result?.from ??
    update.pre_checkout_query?.from ??
    update.my_chat_member?.from ??
    null

  if (!from) return null

  return {
    id: from.id,
    username: from.username ?? null,
    firstName: from.first_name,
    lastName: from.last_name ?? null,
    fullName: [from.first_name, from.last_name].filter(Boolean).join(' '),
    isBot: from.is_bot ?? false,
    languageCode: from.language_code ?? null,
    isPremium: from.is_premium ?? false,
  }
}

function getChatIdFromUpdate(update) {
  return (
    update.message?.chat?.id ??
    update.callback_query?.message?.chat?.id ??
    update.edited_message?.chat?.id ??
    null
  )
}

// Example usage
const user = getUserFromUpdate(update)
// { id: 123456789, username: 'alice', fullName: 'Alice Smith', ... }

const chatId = getChatIdFromUpdate(update)
// 123456789

How it works: if the user has a username, we use t.me/username. If not — a tg://user?id= deep link that opens the profile directly. For MarkdownV2 mentions, we wrap the name in [text](tg://user?id=...).

/**
 * Public profile link (opens in browser / app)
 */
function telegramProfileLink(user) {
  return user.username
    ? `https://t.me/${user.username}`
    : `tg://user?id=${user.id}`
}

/**
 * Mention in MarkdownV2 — clickable name inline in the message text
 */
function telegramMentionMd(user) {
  const name = [user.first_name, user.last_name]
    .filter(Boolean)
    .join(' ')
    .replace(/[_*[\]()~`>#+\-=|{}.!]/g, '\\$&') // escape MarkdownV2
  return `[${name}](tg://user?id=${user.id})`
}

/**
 * Mention in Telegram HTML markup
 */
function telegramMentionHtml(user) {
  const name = [user.first_name, user.last_name].filter(Boolean).join(' ')
  return `<a href="tg://user?id=${user.id}">${name}</a>`
}

// Example usage
const user = { id: 123456789, username: 'alice', first_name: 'Alice', last_name: 'Smith' }

telegramProfileLink(user)  // 'https://t.me/alice'
telegramMentionMd(user)    // '[Alice Smith](tg://user?id=123456789)'
telegramMentionHtml(user)  // '<a href="tg://user?id=123456789">Alice Smith</a>'

How it works: it escapes every character Telegram's MarkdownV2 parser treats as special. This is the "escape everything" recipe — safe for plain user-supplied text, but note it will also escape markdown syntax you wrote yourself (like *bold*), so use it on dynamic values you're inserting into a message template, not on the template's own formatting.

<?php

function escapeMarkdownV2(string $text): string
{
    $reserved = ['_', '*', '[', ']', '(', ')', '~', '`', '>', '#', '+', '-', '=', '|', '{', '}', '.', '!'];

    return str_replace($reserved, array_map(fn ($c) => '\\' . $c, $reserved), $text);
}

// Example usage
$message = escapeMarkdownV2('Price: $10.99 (was $12.99!)');
// "Price: \$10\.99 \(was \$12\.99\!\)"

$bot->sendMessage([
    'chat_id' => $chatId,
    'text' => $message,
    'parse_mode' => 'MarkdownV2',
]);

How it works: Telegram sends a POST request with JSON in the body. PHP reads it via php://input, parses it, and looks for the from field in different parts of the update depending on its type.

<?php

function getTelegramUpdate(): ?array
{
    $body = file_get_contents('php://input');
    return $body ? json_decode($body, true) : null;
}

function getUserFromUpdate(array $update): ?array
{
    $from = $update['message']['from']
        ?? $update['callback_query']['from']
        ?? $update['edited_message']['from']
        ?? $update['inline_query']['from']
        ?? $update['my_chat_member']['from']
        ?? null;

    if (!$from) return null;

    $firstName = $from['first_name'] ?? '';
    $lastName  = $from['last_name'] ?? '';

    return [
        'id'            => (int) $from['id'],
        'username'      => $from['username'] ?? null,
        'first_name'    => $firstName,
        'last_name'     => $lastName,
        'full_name'     => trim("$firstName $lastName"),
        'is_bot'        => (bool) ($from['is_bot'] ?? false),
        'language_code' => $from['language_code'] ?? null,
        'is_premium'    => (bool) ($from['is_premium'] ?? false),
    ];
}

function getChatIdFromUpdate(array $update): ?int
{
    $chatId = $update['message']['chat']['id']
        ?? $update['callback_query']['message']['chat']['id']
        ?? $update['edited_message']['chat']['id']
        ?? null;

    return $chatId !== null ? (int) $chatId : null;
}

// Example usage
$update = getTelegramUpdate();
if (!$update) exit;

$user   = getUserFromUpdate($update);
$chatId = getChatIdFromUpdate($update);

// $user['id']       => 123456789
// $user['username'] => 'alice'
// $chatId           => 123456789

How it works: the function builds a POST request to api.telegram.org/bot{token}/sendMessage with a JSON body. All extra parameters (parse_mode, reply_markup, etc.) are passed via $options and merged with the required fields.

<?php

function telegramSendMessage(
    string $token,
    int|string $chatId,
    string $text,
    array $options = []
): array {
    $url     = "https://api.telegram.org/bot{$token}/sendMessage";
    $payload = array_merge(['chat_id' => $chatId, 'text' => $text], $options);

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

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

    if ($error) throw new \RuntimeException("cURL error: $error");

    return json_decode($response, true);
}

// Example usage — plain message
telegramSendMessage($_ENV['BOT_TOKEN'], $chatId, 'Hello!');

// With Markdown and inline keyboard
telegramSendMessage($_ENV['BOT_TOKEN'], $chatId, 'Choose an action:', [
    'parse_mode'   => 'MarkdownV2',
    'reply_markup' => json_encode([
        'inline_keyboard' => [[
            ['text' => '✅ Confirm', 'callback_data' => 'confirm'],
            ['text' => '❌ Cancel',  'callback_data' => 'cancel'],
        ]],
    ]),
]);

How it works: when registering a webhook (setWebhook) you can pass a secret_token. Telegram will include it in the X-Telegram-Bot-Api-Secret-Token header of every request. We compare with hash_equals to prevent timing attacks.

<?php

function verifyTelegramWebhookSecret(string $expectedSecret): bool
{
    $header = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
    if ($header === '') return false;
    return hash_equals($expectedSecret, $header);
}

// Example usage — first line of the webhook handler
if (!verifyTelegramWebhookSecret($_ENV['TELEGRAM_WEBHOOK_SECRET'])) {
    http_response_code(403);
    exit;
}

$update = json_decode(file_get_contents('php://input'), true);
// ... handle the update

Register the webhook with a secret:

<?php

function registerWebhook(string $token, string $url, string $secret): array
{
    $endpoint = "https://api.telegram.org/bot{$token}/setWebhook";
    $payload  = ['url' => $url, 'secret_token' => $secret, 'allowed_updates' => ['message', 'callback_query']];

    $ch = curl_init($endpoint);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($payload),
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $res = curl_exec($ch);
    curl_close($ch);
    return json_decode($res, true);
}