DEV Community: Serhii

Send Telegram Bot API messages with PHP cURL: status checks, HTML escaping, and timeouts

Serhii — Wed, 02 Sep 2026 18:13:27 +0000

What this tutorial covers and what it does not

We build a small, dependency-free PHP helper that calls the Telegram Bot API sendMessage method over cURL, validates the response carefully, and escapes HTML so the message you intend is the message Telegram renders. The helper is meant to be dropped into a webhook handler, a cron job, or a form-processor script.

This post does not cover webhook setup, signature verification, or rate-limit strategy. Those are separate problems. We focus on the HTTP call itself: status codes, JSON decoding, the ok:false envelope, parse modes, and timeouts.

The wrapper

We keep the function small and explicit. Two arguments matter: the chat id and the text. Everything else is configuration that you can change without touching call sites.

<?php

declare(strict_types=1);

/**
 * Send a message via the Telegram Bot API using cURL.
 *
 * @param int|string $chatId  Telegram chat id.
 * @param string     $text    Message text. Will be escaped for HTML parse_mode.
 * @param array      $extra   Optional overrides: reply_markup, reply_to_message_id, etc.
 *
 * @return array{ok:bool, status:int, error?:string, result?:array}
 */
function tgSendMessage(int|string $chatId, string $text, array $extra = []): array
{
    $token = getenv('TELEGRAM_BOT_TOKEN');
    if (!$token) {
        return ['ok' => false, 'status' => 0, 'error' => 'TELEGRAM_BOT_TOKEN is not set'];
    }

    $url = "https://api.telegram.org/bot{$token}/sendMessage";

    $payload = array_merge([
        'chat_id'    => $chatId,
        'text'       => $text,
        'parse_mode' => 'HTML',
    ], $extra);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => http_build_query($payload),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => ['Content-Type: application/x-www-form-urlencoded'],
    ]);

    $body = curl_exec($ch);

    if ($body === false) {
        $err = curl_error($ch) ?: 'unknown cURL error';
        curl_close($ch);
        return ['ok' => false, 'status' => 0, 'error' => "cURL: {$err}"];
    }

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

    // Body is required: empty response is a failure we want to surface.
    if ($body === '' || $body === null) {
        return ['ok' => false, 'status' => $status, 'error' => 'empty response body'];
    }

    $decoded = json_decode($body, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        return [
            'ok'     => false,
            'status' => $status,
            'error'  => 'invalid JSON: ' . json_last_error_msg(),
        ];
    }

    if (!is_array($decoded)) {
        return ['ok' => false, 'status' => $status, 'error' => 'non-array JSON payload'];
    }

    // Telegram returns 200 even when ok:false. Always trust the envelope.
    if (empty($decoded['ok'])) {
        return [
            'ok'     => false,
            'status' => $status,
            'error'  => (string)($decoded['description'] ?? 'Telegram returned ok:false'),
        ];
    }

    return ['ok' => true, 'status' => $status, 'result' => $decoded['result'] ?? []];
}

Three things to notice:

We use getenv('TELEGRAM_BOT_TOKEN'). The token is read from the environment, never from source. In production, source it from a .env file (parsed by your framework) or from the platform's secret store.
We check the cURL handle with curl_error() only after curl_exec returned false. A false return from curl_exec is the only signal that the request itself failed at the transport layer.
Telegram returns HTTP 200 with a JSON envelope of {"ok":false,"error_code":...,"description":"..."} for application-level failures (chat not found, message too long, parse error). We treat ok:false as a failure regardless of HTTP status.

HTML escaping before sending

If you set parse_mode: HTML, Telegram parses a small subset of HTML: , , , <s>, <code>, <pre>, <a href="...">. Anything that looks like HTML but is not valid in this subset causes a 400 Bad Request: can't parse entities. User-supplied text in particular needs escaping.

function tgHtml(string $s): string
{
    // Order matters: escape & first, then the rest.
    return htmlspecialchars($s, ENT_QUOTES | ENT_HTML5, 'UTF-8');
}

// In a form-to-Telegram pipeline:
$name    = tgHtml($_POST['name']    ?? '');
$message = tgHtml($_POST['message'] ?? '');

$text = "<b>New lead</b>\nName: {$name}\nMessage: {$message}";

$res = tgSendMessage($chatId, $text);

If you escape user input before composing the text and only allow the tags you actually need, the parser will not see stray < and > and your message will not break. If you need to preserve formatting, compose it from safe parts rather than concatenating raw input.

Handling failures you can actually retry

sendMessage is idempotent only if you give it the same message_id to edit — sending the same sendMessage call twice creates two messages. Do not retry blindly. The wrapper returns structured data so the caller can decide.

$res = tgSendMessage($chatId, $text);

if (!$res['ok']) {
    // Log only what is safe to log: do not echo $body verbatim.
    error_log(sprintf(
        '[tg] status=%d error=%s',
        $res['status'],
        $res['error'] ?? 'unknown'
    ));

    // Application errors: 400 chat not found, 429 too many requests.
    // 5xx and transport errors: safe to retry with backoff.
    if ($res['status'] >= 500 || $res['status'] === 0) {
        // schedule a retry in your queue
    } else {
        // give up, notify an admin channel
    }
    return;
}

// $res['result']['message_id'] is available for follow-up edits.
$messageId = $res['result']['message_id'];

The status field is 0 for transport failures (DNS, TLS, timeout, connection refused). 0 is not a real HTTP code, but it is a useful bucket for "never reached Telegram" retries.

Timeouts and connection caps

Two timeouts matter:

CURLOPT_CONNECTTIMEOUT — how long we wait to establish a TCP/TLS connection.
CURLOPT_TIMEOUT — total request budget, including DNS, TLS, send, wait, receive.

For a webhook handler, keep both small. Telegram is fast; a five-second connect and ten-second total is generous. Long timeouts inside a web request translate into hung workers and slow pages. If you need delivery guarantees, push the message into a queue (Redis, database, SQS) and have a worker call tgSendMessage from a CLI process where you can afford longer budgets.

If you batch sends, set a sane CURLOPT_MAXCONNECTS and reuse handles with curl_multi_*. The wrapper above is single-shot because that is the shape that fits into most code paths.

Production notes (optional, treat as such)

Disable parse_mode when you do not need it. Plain text bypasses the entity parser entirely and removes a whole class of errors.
Keep messages under 4096 characters. That is the sendMessage limit. Telegram will return 400 message is too long if you exceed it. For long content, use sendDocument with a generated .txt or .html file.
Use disable_web_page_preview: true when sending URLs you do not control, to avoid accidentally previewing malicious link targets in operator chats.
Read errors from $decoded['description'] rather than HTTP status. Telegram's error_code mirrors HTTP, but description is human-actionable ("Bad Request: message is too long", "Forbidden: bot was blocked by the user").
Watch for 429. Telegram rate-limits per chat and per bot. Back off and retry after retry_after (seconds) the API includes in the error envelope.

Quick checklist

Token is read from the environment.
curl_exec false is treated as transport failure with the cURL error string.
json_last_error() is checked after json_decode.
Telegram's ok:false envelope is treated as failure even on HTTP 200.
HTML user input is passed through htmlspecialchars before composition.
Timeouts are short for in-request calls, longer for background workers.

A small helper like this is often enough. Once you have a single well-behaved call site, the second and third call sites become trivial, and you stop losing messages to silent ok:false responses.

If you want a reference for the full set of sendMessage parameters and reply markup shapes, the Telegram Bot API reference is the canonical place to look.

This pattern — small cURL wrapper, strict envelope checks, HTML escaping, short timeouts — is the same one BotCreator uses when shipping Telegram bots and Mini Apps for clients.

Send Website Form Submissions to Telegram with PHP

Serhii — Wed, 02 Sep 2026 16:48:10 +0000

What we build and what we do not claim

A static HTML form on your site posts to a small PHP handler. The handler validates the input, generates a lead ID, persists the lead, and calls the Telegram Bot API sendMessage to a manager's chat. The manager sees the lead instantly and can press a button to "take" it.

This tutorial is honest about its limits:

It is a forwarding pattern, not a CRM. If you need multi-pipeline deal tracking, use a real CRM and treat Telegram as the notification + hand-off channel.
A weak phone regex is a sanity check, not a real validator. If phone format is business-critical, use a library such as libphonenumber (or a server-side validator) and normalize before storage.
The core handler is single-process. If you run multiple PHP-FPM workers behind a load balancer, the optional webhook section explains how to avoid double-processing.

If you only need "form → manager chat", the core path below is enough. Buttons and the webhook are labeled optional.

Core: HTML form → PHP → Telegram

1. The form

Keep it short. Name, phone, and a free-text field are usually enough; add UTM tags if your analytics needs them.

<form action="/leads.php" method="post">
  <input name="name" required maxlength="100">
  <input name="phone" required maxlength="32">
  <textarea name="message" maxlength="1000"></textarea>
  <input type="hidden" name="page" value="/pricing">
  <button type="submit">Send</button>
</form>

2. The PHP handler

Two environment variables, both read via getenv so they are not committed to the repo:

TELEGRAM_BOT_TOKEN — the bot you created with @BotFather.
TELEGRAM_MANAGER_CHAT_ID — the numeric chat ID of the manager (or a group where the bot has been added).

The handler validates input, generates a 14-character lead ID, persists the lead to MySQL before calling Telegram (so a webhook callback can look it up later), and only then sends the message. If Telegram fails, the lead is still saved and the manager can be notified by other means.

<?php
// leads.php — receives form posts and forwards them to a Telegram manager chat.

declare(strict_types=1);

function tg_send(string $method, array $params): array {
    $token = getenv('TELEGRAM_BOT_TOKEN');
    if (!$token) {
        return ['ok' => false, 'description' => 'TELEGRAM_BOT_TOKEN not set'];
    }

    $ch = curl_init("https://api.telegram.org/bot{$token}/{$method}");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $params,
        CURLOPT_TIMEOUT => 10,
    ]);
    $raw = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($raw === false || $code !== 200) {
        return ['ok' => false, 'description' => "HTTP {$code}", 'raw' => $raw];
    }
    $decoded = json_decode((string) $raw, true);
    if (json_last_error() !== JSON_ERROR_NONE || !is_array($decoded)) {
        return ['ok' => false, 'description' => 'Invalid JSON from Telegram'];
    }
    return $decoded;
}

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Method Not Allowed');
}

$name    = trim((string) ($_POST['name'] ?? ''));
$phone   = trim((string) ($_POST['phone'] ?? ''));
$message = trim((string) ($_POST['message'] ?? ''));
$page    = trim((string) ($_POST['page'] ?? ''));

if ($name === '' || $phone === '') {
    http_response_code(422);
    exit('Name and phone are required.');
}

// Sanity check only. Replace with a real validator if format matters.
if (!preg_match('/^[+0-9 ()\-]{6,32}$/', $phone)) {
    http_response_code(422);
    exit('Phone looks invalid.');
}

// 14 hex chars, plenty of headroom for a website lead table.
$leadId = bin2hex(random_bytes(7));

// Persist BEFORE sendMessage. The lead ID is what the Take-lead callback will look up.
$pdo = new PDO('mysql:host=127.0.0.1;dbname=site;charset=utf8mb4', getenv('DB_USER'), getenv('DB_PASS'), [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);
$stmt = $pdo->prepare(
    'INSERT INTO leads (id, name, phone, message, page, status, created_at)
     VALUES (?, ?, ?, ?, ?, "new", NOW())'
);
$stmt->execute([$leadId, $name, $phone, $message, $page]);

$chatId = getenv('TELEGRAM_MANAGER_CHAT_ID');

$text = "<b>New lead</b> #{$leadId}\n"
      . "Name: " . htmlspecialchars($name, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') . "\n"
      . "Phone: " . htmlspecialchars($phone, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') . "\n"
      . "Page: " . htmlspecialchars($page, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') . "\n"
      . "Message: " . htmlspecialchars($message, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');

$replyMarkup = json_encode([
    'inline_keyboard' => [
        [
            // callback_data has a hard 64-byte limit. "take:" + 14 hex = 19 bytes, fine.
            ['text' => 'Take lead', 'callback_data' => "take:{$leadId}"],
            ['text' => 'Reject',   'callback_data' => "drop:{$leadId}"],
        ],
    ],
]);

$resp = tg_send('sendMessage', [
    'chat_id'      => $chatId,
    'text'         => $text,
    'parse_mode'   => 'HTML',
    'reply_markup' => $replyMarkup,
]);

if (!($resp['ok'] ?? false)) {
    error_log('Telegram sendMessage failed: ' . ($resp['description'] ?? 'unknown'));
    // Lead is already saved, so the manager can be retried out of band.
}

header('Location: /thank-you.html');
exit;

A few things worth calling out:

htmlspecialchars runs before parse_mode=HTML. Telegram interprets , , <a>, and friends literally; an unescaped < in user input can break your markup or, worse, inject a link.
Telegram replies with {"ok": true, "result": ...} on success and {"ok": false, "description": "..."} on failure. Always branch on ok, not on HTTP 200 alone — Telegram returns 200 for almost everything, including rejected requests.
The lead row is inserted before sendMessage is called and before $leadId is used in callback_data. This is the order that matters: if you reversed it, a fast callback from a manager could arrive before the row exists.
A weak regex is a sanity check. If your business rules require a strict format, plug a real validator in at the preg_match line.

Optional: the Take-lead callback

When the manager taps Take lead, Telegram POSTs an update to your webhook (next section). The handler below answers the alert and updates the DB. The take: payload is short on purpose — callback_data is capped at 64 bytes.

<?php
// webhook.php — receives callback_query updates from Telegram.

declare(strict_types=1);

$body = file_get_contents('php://input');
$update = json_decode($body, true);
if (json_last_error() !== JSON_ERROR_NONE || !is_array($update)) {
    http_response_code(400);
    exit('bad json');
}

// Idempotency: Telegram may redeliver. Skip already-processed update_id.
$updateId = (int) ($update['update_id'] ?? 0);
if ($updateId > 0) {
    $pdo = new PDO('mysql:host=127.0.0.1;dbname=site;charset=utf8mb4', getenv('DB_USER'), getenv('DB_PASS'), [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ]);
    try {
        $pdo->prepare('INSERT INTO processed_updates (update_id) VALUES (?)')->execute([$updateId]);
    } catch (PDOException $e) {
        // Duplicate key — already handled. Just acknowledge.
        echo 'OK';
        exit;
    }
}

$cb = $update['callback_query'] ?? null;
if (!$cb) { echo 'OK'; exit; }

$token = getenv('TELEGRAM_BOT_TOKEN');
$cbId  = $cb['id'];
$data  = (string) ($cb['data'] ?? '');

// Always answer the callback so the button stops showing the loading spinner.
$ch = curl_init("https://api.telegram.org/bot{$token}/answerCallbackQuery");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => ['callback_query_id' => $cbId, 'text' => 'Marked as taken'],
]);
curl_exec($ch);
curl_close($ch);

if (str_starts_with($data, 'take:')) {
    $leadId = substr($data, 5);
    $pdo->prepare('UPDATE leads SET status = "taken", taken_at = NOW() WHERE id = ? AND status = "new"')
        ->execute([$leadId]);
}

echo 'OK';

Two production details that are easy to get wrong:

Idempotency by update_id only is not enough when you run more than one PHP-FPM worker. Telegram will redeliver an update if your 200 OK takes too long, and two workers can race on the same update_id. The INSERT ... processed_updates above is the source of truth: the unique key on update_id guarantees only one worker proceeds. If you want to avoid MySQL for this, a Redis SETNX with a TTL works the same way.
The t.me/Bot?start=lead_ID trick is sometimes suggested as a "resume the lead chat" shortcut. It only deep-links /start to your bot — the bot still has to map the payload back to a lead, then to a session, then to a chat. Prefer short callback_data for in-chat hand-off and only use start= when you genuinely want the lead to open a fresh conversation with a known context.

Optional: registering the webhook

A self-signed certificate is fine; Telegram will accept it. Replace the values and run once. Do not paste this into a shell history that gets logged — the secret_token is sensitive. Prefer running it from a script file with chmod 600, or skip the secret and rely on the URL being unguessable.

curl -sS -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhook.php",
    "secret_token": "change-me-to-a-long-random-string",
    "allowed_updates": ["callback_query", "message"]
  }'

Production notes

Logging IPs. If you log $_SERVER['REMOTE_ADDR'] for spam analysis, remember that behind Cloudflare or Nginx this is the proxy, not the client. Use CF-Connecting-IP (Cloudflare) or your load balancer's header, and treat those as untrusted user input. Also consider GDPR: raw IPs are personal data in many jurisdictions — hash or truncate before storage if you do not need the full value.
Spam. A bot-friendly form is also a spammer-friendly form. Add a honeypot field, rate-limit by IP, and consider a CAPTCHA on suspicious traffic. None of that replaces monitoring the manager chat for junk.
Reliability. sendMessage can fail (rate limits, transient 5xx). A simple flock-based queue or a wp cron / systemd retry that re-reads leads where status='new' and telegram_sent_at IS NULL is enough for most small sites. Email fallback is fine as a last resort — but you started this project because email is exactly the channel that loses leads.
Secrets. getenv is the minimum. In production, read from your platform's secret store and rotate TELEGRAM_BOT_TOKEN if it ever appears in a log.

Verifying it works

Submit the form on staging. You should see the lead in MySQL and a message in the manager's Telegram.
Tap Take lead. The button should stop spinning, the alert should read "Marked as taken", and leads.status should flip to taken.
Re-deliver the same webhook update manually (with curl and the same JSON body) and confirm the second request is a no-op — that is your idempotency check doing its job.

That is the entire pipeline. A few hundred lines, a database table, and one HTTPS endpoint — and a form submission lands in a manager's pocket in under a second.

If you would rather skip the handler and just have the pipeline running, BotCreator can ship a managed version of this flow with the manager buttons, retry, and webhook already wired up.

Customer data security in the Telegram bot: what to store and what not to

Serhii — Sun, 30 Aug 2026 17:42:04 +0000

What can and cannot be stored in the Telegram bot, how to set up employee access and accept payment without storing cards. Customer trust as an argument for business.