Перейти к содержанию
9 минут чтения
Тема: Практика Telegram Bot API · Контакты · PHP

Как получить номер телефона пользователя в Telegram-боте

Для примера возьмём запись на консультацию: после выбора времени бот предложит оставить телефон для обратного звонка. Пользователь сможет поделиться контактом или продолжить без звонка. Разберём кнопку, входящее сообщение и проверки, которые не позволят записать чужой контакт как номер отправителя.

Что бот может узнать о телефоне

Обычное сообщение от пользователя содержит его Telegram ID, имя и иногда username, но не телефон. Получить номер произвольного человека по user_id через Bot API нельзя. Для нашего сценария пользователь сам передаёт контакт кнопкой request_contact.

Такая кнопка относится к ReplyKeyboardMarkup и работает только в личном чате. InlineKeyboardMarkup под сообщением для запроса телефона не подходит: callback_data передаёт данные нажатия, но не раскрывает контакт. В группе предложите пользователю открыть личный чат с ботом.

Перед кнопкой объясните, зачем нужен телефон и что произойдёт после передачи. В нашем примере номер нужен для звонка по выбранной записи. Получение контакта само по себе не означает согласия на рассылку. Не подменяйте Telegram ID номером телефона в качестве постоянного ключа пользователя.

Отправляем кнопку запроса контакта

Сначала сохраните в своей БД шаг awaiting_phone для текущего bot_id, chat_id и user_id, время истечения запроса и идентификатор записи на консультацию. Затем отправьте sendMessage с таким JSON-телом. Число chat_id замените на ID своего тестового личного чата; этот запрос действительно покажет пользователю сообщение и клавиатуру.

JSON · тело sendMessage
{
  "chat_id": 123456789,
  "text": "Оставьте телефон для звонка по вашей записи или продолжите без звонка.",
  "reply_markup": {
    "keyboard": [
      [{"text": "Поделиться телефоном", "request_contact": true}],
      [{"text": "Без звонка"}]
    ],
    "resize_keyboard": true,
    "one_time_keyboard": true
  }
}

При прямом подключении это POST https://api.telegram.org/bot<TOKEN>/sendMessage с Content-Type: application/json. Токен храните в окружении приложения и не записывайте полный URL с ним в журнал. При ошибке API не переводите запрос телефона в завершённый: пользователь мог не увидеть кнопку.

one_time_keyboard просит клиент скрыть клавиатуру после использования, но не удаляет её окончательно. После принятия номера, отказа или отмены отправим отдельное remove_keyboard. Не ждите callback_query: нажатие request_contact приходит как message.contact.

Проверяем, чей контакт прислал пользователь

Контакт можно отправить и вручную из адресной книги. Поэтому наличия phone_number недостаточно. Для политики «принимаем только собственный номер» сравниваем contact.user_id с message.from.id. Поле contact.user_id необязательное: если его нет, принадлежность не подтверждена, и мы просим воспользоваться кнопкой ещё раз.

Ниже — функция извлечения для 64-битного PHP 8.2+. Она вызывается только после проверки подлинности webhook. Переменная $message — массив из update['message']; параметры другого пользователя не берутся из формы на сайте или callback_data.

PHP · phone.php
<?php
declare(strict_types=1);

function ownPhone(array $message): ?string
{
    $from = $message['from'] ?? null;
    $chat = $message['chat'] ?? null;
    $contact = $message['contact'] ?? null;
    if (!is_array($from) || !is_array($chat) || !is_array($contact)
        || ($chat['type'] ?? null) !== 'private'
        || !is_int($from['id'] ?? null)
        || ($from['is_bot'] ?? false)
        || !is_int($chat['id'] ?? null)
        || $chat['id'] !== $from['id']
        || !is_int($contact['user_id'] ?? null)
        || $contact['user_id'] !== $from['id']) {
        return null;
    }
    $phone = $contact['phone_number'] ?? null;
    if (!is_string($phone) || trim($phone) === '') {
        return null;
    }
    // Сохраняем переданный номер, не угадываем страну и префикс.
    return trim($phone);
}

Имя внутри contact не доказывает принадлежность номера: оно может отличаться от профиля. vcard для этой проверки не нужен. Не записывайте произвольный текст «+7…» как подтверждённый контакт и не считайте отсутствующий user_id совпадением.

Проверка связывает контакт с отправителем Telegram. Она не является SMS-проверкой владения SIM-картой в момент оформления и не подходит как единственный фактор для критичного действия. Если номер участвует во входе или восстановлении аккаунта, используйте отдельную процедуру подтверждения.

Принимаем контакт только на нужном шаге

Даже собственный контакт не нужно автоматически привязывать к последней заявке. В транзакции загрузите активный запрос по bot_id, chat_id и user_id, проверьте awaiting_phone и expires_at, а затем решите, что делать с сообщением. Если пользователь уже отменил запись, старый контакт не должен открывать её снова.

  • Для активного запроса и собственного контакта сохраните номер вместе с Telegram user_id, ID записи и временем передачи; завершите шаг.

  • Для текста «Без звонка» или /cancel завершите запрос без номера. Если звонок обязателен по условиям услуги, заранее объясните это и предложите другой способ связи.

  • Для чужого контакта, отсутствующего user_id или обычного текста оставьте шаг активным и попросите нажать кнопку.

  • Для завершённого или просроченного запроса не меняйте телефон в профиле. Уберите старую клавиатуру и предложите начать действие заново.

Проверку повторного update_id, сохранение номера, смену шага и запись исходящего ответа выполняйте атомарно. Ключ дедупликации — (bot_id, update_id). Повтор webhook после успешного сохранения не должен создавать новую запись на звонок. Схема такого хранения приведена в пошаговой анкете на PHP.

Если приложение приводит номера к единому формату, храните исходное значение отдельно. Не добавляйте код страны по языку интерфейса или текущему местоположению пользователя. Полные контакты и тела webhook с телефонами не нужны в обычном техническом журнале; доступ и срок хранения задавайте для самой функции записи.

Убираем клавиатуру после завершения

После успешного сохранения номера отправьте подтверждение с remove_keyboard. При отказе используйте тот же reply_markup, но другой текст, например «Продолжим без звонка». Сначала завершается транзакция, затем worker отправляет ответ.

JSON · подтверждение sendMessage
{
  "chat_id": 123456789,
  "text": "Телефон сохранён для звонка по вашей записи.",
  "reply_markup": {"remove_keyboard": true}
}

Не повторяйте полный номер в сообщении без необходимости. Если ответ потерялся после сохранения, повторно пришедший контакт не должен заново выполнять бизнес-действие. При неизвестном результате sendMessage не запускайте бесконечную повторную отправку.

Отправка через PHP SDK BotGate

BotGate передаёт те же параметры request_contact и remove_keyboard. Для вызова нужен API-ключ BotGate, публичный ID подключённого бота и chat_id. Сначала установите клиент:

Bash · установка
composer require botgate/sdk

Для примера следующий самостоятельный скрипт отправит запрос телефона в указанный тестовый чат. BOTGATE_API_KEY, BOTGATE_BOT_ID и TELEGRAM_CHAT_ID должны быть настоящими переменными окружения процесса: обычный PHP не загружает файл .env сам.

PHP · request-phone.php
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';

use BotGate\Client;
use BotGate\Config;

$apiKey = getenv('BOTGATE_API_KEY');
$botId = getenv('BOTGATE_BOT_ID');
$chatId = getenv('TELEGRAM_CHAT_ID');
if (!$apiKey || !$botId || !$chatId || !preg_match('/^[1-9][0-9]*$/', $chatId)) {
    throw new RuntimeException('Задайте API-ключ, публичный ID бота и ID личного чата.');
}
$bot = Client::fromConfig(new Config(apiKey: $apiKey, maxRetries: 0))->bot($botId);
$response = $bot->call('sendMessage', [
    'chat_id' => $chatId,
    'text' => 'Оставьте телефон для звонка по вашей записи или продолжите без звонка.',
    'reply_markup' => [
        'keyboard' => [
            [['text' => 'Поделиться телефоном', 'request_contact' => true]],
            [['text' => 'Без звонка']],
        ],
        'resize_keyboard' => true,
        'one_time_keyboard' => true,
    ],
]);
echo 'Запрос телефона отправлен.' . PHP_EOL;

Скрипт показывает только исходящий вызов; активный шаг и сохранение контакта подключите по разделу выше. Автоматические повторы SDK отключены: после таймаута сначала разберите неизвестный результат. Подпись входящих событий и настройку адреса показывает документация webhook.

Что проверить в тестовом диалоге

  • Собственный контакт через кнопку принимается один раз и клавиатура исчезает.

  • Контакт другого человека и контакт без user_id не проходят проверку владельца.

  • Текст с номером и фото не записываются как подтверждённый телефон.

  • «Без звонка», /cancel и просроченный запрос не сохраняют новый номер.

  • Повтор того же update_id не создаёт ещё один звонок или заявку.

  • Старое сообщение с контактом после завершения шага не перезаписывает данные профиля.

Если кнопки нет, сначала проверьте личный тип чата и расположение request_contact внутри keyboard. Если кнопка есть, а номер не сохраняется, проверьте получение message.contact и активный шаг. Диагностика транспорта вынесена в статью о webhook.

Документация