Введение

Официальная документация Telegram Bot API точная, но «сухая»: много методов и мало прикладных сценариев. Этот гайд — практический слой поверх core.telegram.org/bots/api: от первого getMe до webhook, inline-кнопок, Mini Apps и боевых проектов на PHP.

Для кого этот раздел

• PHP-разработчики (чистый PHP, Yii2, Laravel);
• фронтенд-разработчики Mini Apps (React / Vue);
• те, кто уже читал официальные docs и хочет рабочие паттерны: идемпотентность, secret_token, очереди, проверка initData.

Бизнес-кейсы и «зачем бот салону» остаются в блоге. Здесь — только техника.

Проверка окружения перед стартом

Убедитесь, что PHP видит cURL и может достучаться до api.telegram.org. Запустите в терминале:

php -m | grep curl
curl -I https://api.telegram.org

Ожидаемый вывод: curl в списке модулей и HTTP/2 200 (или 301/302) от Telegram. Если cURL нет — apt-get install php-curl / brew install php / включите расширение в php.ini.

Минимальный «Hello API» на PHP

Сразу после получения токена у @BotFather (см. следующую главу) проверьте, что бот жив. Ниже — разовый скрипт без фреймворков; в главе про HTTP-клиент мы вынесем это в переиспользуемую функцию telegramApi().

<?php
// test-token.php — запуск: php test-token.php
$token = getenv('TELEGRAM_BOT_TOKEN');
if (!$token) {
    fwrite(STDERR, "TELEGRAM_BOT_TOKEN не задан в окружении\n");
    exit(1);
}

$url = "https://api.telegram.org/bot{$token}/getMe";
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Accept: application/json'],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlErrno = curl_errno($ch);
$curlError = curl_error($ch);
curl_close($ch);

if ($curlErrno) {
    fwrite(STDERR, "cURL error {$curlErrno}: {$curlError}\n");
    exit(1);
}
if ($httpCode !== 200) {
    fwrite(STDERR, "HTTP {$httpCode}: {$response}\n");
    exit(1);
}

$data = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    fwrite(STDERR, "Invalid JSON: " . json_last_error_msg() . "\n");
    exit(1);
}

if (!($data['ok'] ?? false)) {
    fwrite(STDERR, "API error: " . json_encode($data, JSON_UNESCAPED_UNICODE) . "\n");
    exit(1);
}

$bot = $data['result'];
echo "OK: @{$bot['username']} (id={$bot['id']}, name={$bot['first_name']})\n";

Что вернёт Telegram — разбор JSON

При успешном запросе getMe приходит такой ответ:

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "My Cool Bot",
    "username": "mycoolbot",
    "can_join_groups": true,
    "can_read_all_group_messages": false,
    "supports_inline_queries": false,
    "can_connect_to_business": false,
    "has_main_web_app": false
  }
}

• ok — true означает успех на уровне API. Если false — смотрите error_code и description (например, 401 Unauthorized — неверный токен).
• result — объект User бота. Поля id и username понадобятся для deep-linking и проверки входящих обновлений.
• can_read_all_group_messages — false по умолчанию. Чтобы бот видел все сообщения в группе, включите Privacy Mode в @BotFather → Bot Settings → Group Privacy → Disable.

Как смотреть результат в терминале

Запустите скрипт:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 php test-token.php
# OK: @mycoolbot (id=123456789, name=My Cool Bot)

Если токен неверен — увидите:

API error: {"ok":false,"error_code":401,"description":"Unauthorized"}

Для отладки сложных ответов используйте json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) — так структура читается мгновенно.

Карта гайда (кратко)

• Старт — BotFather, токен, getMe;
• Обновления — getUpdates, long polling, webhook, миграция;
• Сообщения и клавиатуры — sendMessage, HTML/Markdown, фото/документы, inline, callback;
• PHP — HTTP-клиент, ошибки API, Yii2, Laravel, БД и FSM;
• Mini Apps и платежи — отдельными главами;
• Проекты — заявка с сайта, магазин, очередь.

Дальше: Bot API vs MTProto — почему для ботов почти всегда нужен именно Bot API.