Перейти к содержанию
16 минут чтения
Тема: Практика Telegram Bot API · Запись на услуги · База данных

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

Для примера возьмём запись на 30-минутную консультацию. Клиент выбирает день и время в личном чате с ботом. Интервал удерживается до пяти минут, пока клиент подтверждает выбор. Если два человека нажмут на одно время, подтвердить его сможет только тот, кто получил действующий резерв.

Создаём интервалы и показываем свободное время

Заранее создайте по одной строке на каждый 30-минутный интервал консультанта. В booking_slots храните id, resource_id, starts_at, ends_at, state, telegram_user_id, reservation_id и hold_until. Держите уникальный ключ (resource_id, starts_at) и формируйте интервалы из одной сетки без пересечений для каждого консультанта.

  • free — интервал свободен. Поля владельца, резерва и срока пустые.

  • held — интервал удерживается до hold_until. Идентификатор резерва отличает текущую попытку от предыдущих.

  • booked — клиент подтвердил запись. Владелец и идентификатор резерва сохраняются, срок удержания очищается.

Рабочие часы и выбор дня считайте в часовом поясе услуги, например Europe/Moscow. В PostgreSQL храните моменты начала, конца и срока резерва как timestamptz. Рядом с кнопками указывайте пояс. Для выбранной даты считайте полуоткрытый интервал от местной полуночи до следующей местной полуночи и переводите обе границы в моменты времени. Такой расчёт учитывает и пояса с переходом на летнее время.

Показывайте будущие строки со статусом free и строки held, у которых срок уже истёк. К моменту нажатия доступность может измениться, поэтому бот проверяет её повторно при резервировании.

Эта модель подходит для услуг одинаковой длительности на фиксированной сетке. Если можно записаться с произвольного времени или на разные по длине услуги, соседние старты могут пересекаться. Тогда проверяйте пересечение диапазонов на уровне БД. Например, в PostgreSQL можно использовать ограничение исключения для активных интервалов одного ресурса.

Связываем кнопки Telegram с действиями

После команды /book покажите кнопки с датами, затем список доступных интервалов. При выборе времени создайте резерв и отобразите его срок, кнопку «Подтвердить» и кнопку «Отменить». Для кнопок используйте короткие значения callback_data длиной от 1 до 64 байт.

Выбор даты, кнопки 10:30 и 11:00, временный резерв до 10:05 с подтверждением или отменой и подтверждённая запись.
Выбор даты, кнопки 10:30 и 11:00, временный резерв до 10:05 с подтверждением или отменой и подтверждённая запись.
Схема кнопок и состояний из статьи, не снимок Telegram. Даты и срок учебные; кнопки времени взяты из JSON-примера.
JSON · inline-кнопки
{
  "inline_keyboard": [
    [{ "text": "10:30", "callback_data": "hold:183" }],
    [{ "text": "11:00", "callback_data": "hold:184" }]
  ]
}

После успешного резерва используйте confirm:<reservation_id> и cancel:<reservation_id>. Например, UUID длиной 36 символов вместе с префиксом помещается в лимит. Получателя действий определяйте по callback_query.from.id из проверенного обновления. Сервер проверяет формат ID, владельца и текущее состояние записи. Кнопки могут остаться в старых сообщениях.

Вызывайте answerCallbackQuery для каждого нажатия, включая устаревшие кнопки. Если операция занимает время, быстро подтвердите получение нажатия и покажите результат отдельным редактированием сообщения после фиксации БД. Настройка приёма нажатий разобрана в руководстве по inline-кнопкам.

Резервируем время атомарно

Ниже фрагменты для PostgreSQL с именованными параметрами драйвера приложения. Для каждого изменения начните транзакцию и заблокируйте целевую строку через SELECT … FOR UPDATE. При выборе ищите по id, при подтверждении и отмене — по уникальному reservation_id. После получения блокировки выполните следующий условный запрос. В PostgreSQL statement_timestamp() в этом запросе отражает время его начала, уже после ожидания блокировки.

SQL · резерв свободного или просроченного интервала
UPDATE booking_slots
SET state = 'held',
    telegram_user_id = :user_id,
    reservation_id = :new_reservation_id,
    hold_until = LEAST(
      statement_timestamp() + interval '5 minutes',
      starts_at
    )
WHERE id = :slot_id
  AND starts_at > statement_timestamp()
  AND (state = 'free'
       OR (state = 'held' AND hold_until <= statement_timestamp()))
RETURNING reservation_id, hold_until;

Для нового резерва сгенерируйте UUID на сервере. Если заблокированная строка уже удерживается тем же клиентом и срок не истёк, верните текущие ID и время окончания без продления. Если запрос обновил строку, зафиксируйте транзакцию и покажите клиенту срок. Если строка не обновилась, перечитайте расписание и предложите другое время.

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

Подтверждаем и отменяем запись

Подтверждение проверяет ID текущего резерва, владельца и срок. Старое сообщение не сможет подтвердить чужой или заменённый резерв.

SQL · подтверждение действующего резерва
UPDATE booking_slots
SET state = 'booked', hold_until = NULL
WHERE reservation_id = :reservation_id
  AND telegram_user_id = :user_id
  AND state = 'held'
  AND hold_until > statement_timestamp()
  AND starts_at > statement_timestamp()
RETURNING id, starts_at;

Если строка уже booked с тем же ID и владельцем, повтор подтверждения возвращает сведения о той же записи. Иначе отсутствие обновлённой строки означает, что подтвердить выбор больше нельзя. Предложите выбрать время снова. Если ведёте историю записей, сохраните запись о подтверждении в той же транзакции и добавьте уникальность по ID резерва.

Для отмены снова проверьте владельца и ID. В примере до начала консультации клиент может освободить удерживаемый или подтверждённый интервал. После начала состояние остаётся в расписании. Для платной услуги здесь же примените своё правило отмены.

SQL · отмена резерва или записи
UPDATE booking_slots
SET state = 'free',
    telegram_user_id = NULL,
    reservation_id = NULL,
    hold_until = NULL
WHERE reservation_id = :reservation_id
  AND telegram_user_id = :user_id
  AND state IN ('held', 'booked')
  AND starts_at > statement_timestamp()
RETURNING id;

При повторной отмене с тем же ID запрос больше не меняет строку. Если между нажатиями время занял другой клиент, у него будет новый ID резерва. Бот может показать нейтральный ответ «Эта запись уже недоступна». После подтверждения отдельный планировщик может отправить напоминание о визите. Перед отправкой проверьте, что запись всё ещё действует и её ID совпадает с заданием.

Подключаем резервирование к обработчику PHP

Для примера используем PHP 8.3+ с pdo_pgsql и PostgreSQL. Приёмник webhook уже проверяет подлинность события. Функция ниже отвечает за расписание и вызывается после этой проверки; внешние API-запросы выполняются после её завершения. В отдельной тестовой БД создайте таблицу:

SQL · схема фиксированных интервалов
CREATE TABLE booking_slots (
  id bigserial PRIMARY KEY, resource_id bigint NOT NULL,
  starts_at timestamptz NOT NULL, ends_at timestamptz NOT NULL,
  state text NOT NULL DEFAULT 'free' CHECK (state IN ('free', 'held', 'booked')),
  telegram_user_id bigint, reservation_id uuid UNIQUE, hold_until timestamptz,
  UNIQUE (resource_id, starts_at), CHECK (ends_at > starts_at),
  CHECK (
    (state = 'free' AND telegram_user_id IS NULL AND reservation_id IS NULL AND hold_until IS NULL)
    OR (state = 'held' AND telegram_user_id IS NOT NULL AND reservation_id IS NOT NULL AND hold_until IS NOT NULL)
    OR (state = 'booked' AND telegram_user_id IS NOT NULL AND reservation_id IS NOT NULL AND hold_until IS NULL)
  )
);
INSERT INTO booking_slots (resource_id, starts_at, ends_at)
VALUES (1, '2026-12-01 10:00:00+03', '2026-12-01 10:30:00+03');

Замените дату на будущую. Этот пример использует фиксированные интервалы по 30 минут и одного консультанта. Уникальность начала не запрещает произвольные пересекающиеся интервалы: создание расписания должно сохранять выбранную сетку. Для подтверждений и отмены сохраняется случайный ID резерва; числовой ID интервала используется только при выборе времени.

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

function bookingAction(PDO $db, int $userId, string $action, string $key): ?array
{
    if (!in_array($action, ['hold', 'confirm', 'cancel'], true) || $userId <= 0) {
        throw new InvalidArgumentException('Некорректное действие');
    }
    if ($action === 'hold' ? !preg_match('/\A[1-9][0-9]{0,17}\z/', $key)
        : !preg_match('/\A[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}\z/', $key)) {
        return null;
    }
    $db->beginTransaction();
    try {
        $column = $action === 'hold' ? 'id' : 'reservation_id';
        $q = $db->prepare("SELECT id FROM booking_slots WHERE $column = ? FOR UPDATE");
        $q->execute([$key]);
        $id = $q->fetchColumn();
        if ($id === false) {
            $db->commit();
            return null;
        }
        // Новый statement начинается после получения блокировки.
        $q = $db->prepare('SELECT *,
            (starts_at > statement_timestamp())::int AS future,
            (hold_until > statement_timestamp())::int AS alive
            FROM booking_slots WHERE id = ?');
        $q->execute([$id]);
        $slot = $q->fetch(PDO::FETCH_ASSOC);
        $mine = (string) $slot['telegram_user_id'] === (string) $userId;
        $held = $slot['state'] === 'held' && (int) $slot['alive'] === 1;
        $result = null;
        if ($action === 'hold') {
            if ($mine && $held && (int) $slot['future'] === 1) {
                $result = $slot; // Повтор не продлевает срок удержания.
            } elseif ((int) $slot['future'] === 1 &&
                ($slot['state'] === 'free' || ($slot['state'] === 'held' && !$held))) {
                $hex = bin2hex(random_bytes(16));
                $uuid = substr($hex, 0, 8).'-'.substr($hex, 8, 4).'-'.substr($hex, 12, 4)
                    .'-'.substr($hex, 16, 4).'-'.substr($hex, 20);
                $q = $db->prepare("UPDATE booking_slots SET state = 'held',
                    telegram_user_id = ?, reservation_id = ?,
                    hold_until = LEAST(statement_timestamp() + interval '5 minutes', starts_at)
                    WHERE id = ? AND starts_at > statement_timestamp() RETURNING *");
                $q->execute([$userId, $uuid, $id]);
                $result = $q->fetch(PDO::FETCH_ASSOC) ?: null;
            }
        } elseif ($mine && $slot['reservation_id'] === $key) {
            if ($action === 'confirm' && $slot['state'] === 'booked') {
                $result = $slot; // Уже подтверждённая запись имеет тот же ID.
            } elseif ($action === 'confirm' && $held) {
                $q = $db->prepare("UPDATE booking_slots SET state = 'booked', hold_until = NULL
                    WHERE id = ? AND starts_at > statement_timestamp()
                    AND hold_until > statement_timestamp() RETURNING *");
                $q->execute([$id]);
                $result = $q->fetch(PDO::FETCH_ASSOC) ?: null;
            } elseif ($action === 'cancel') {
                $q = $db->prepare("UPDATE booking_slots SET state = 'free',
                    telegram_user_id = NULL, reservation_id = NULL, hold_until = NULL
                    WHERE id = ? AND starts_at > statement_timestamp() RETURNING *");
                $q->execute([$id]);
                $result = $q->fetch(PDO::FETCH_ASSOC) ?: null;
            }
        }
        $db->commit();
        return $result;
    } catch (Throwable $error) {
        if ($db->inTransaction()) $db->rollBack();
        throw $error;
    }
}

Подключение создавайте один раз на обработчик: new PDO(getenv('BOOKING_DSN'), getenv('BOOKING_DB_USER'), getenv('BOOKING_DB_PASSWORD'), [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_EMULATE_PREPARES => false]). DSN имеет вид pgsql:host=127.0.0.1;port=5432;dbname=booking_demo; пароль хранится в окружении. Функция сама открывает транзакцию, поэтому не оборачивайте её ещё одной.

PHP · вызов из проверенного callback_query
// $db — PDO; $callback — callback_query из проверенного webhook.
$actor = $callback['from']['id'] ?? null;
$payload = $callback['data'] ?? null;
if (!is_int($actor) || !is_string($payload)) return;
$parts = explode(':', $payload, 2);
if (count($parts) !== 2 || !in_array($parts[0], ['hold', 'confirm', 'cancel'], true)) return;
$slot = bookingAction($db, $actor, $parts[0], $parts[1]);
if ($slot === null) {
    $text = 'Это время уже недоступно. Откройте расписание заново.';
    $buttons = [];
} elseif ($slot['state'] === 'held') {
    $until = (new DateTimeImmutable($slot['hold_until']))->setTimezone(new DateTimeZone('Europe/Moscow'));
    $text = 'Время удерживается до '.$until->format('H:i').' (Москва).';
    $buttons = [[
        ['text' => 'Подтвердить', 'callback_data' => 'confirm:'.$slot['reservation_id']],
        ['text' => 'Отменить', 'callback_data' => 'cancel:'.$slot['reservation_id']],
    ]];
} else {
    $text = $slot['state'] === 'booked' ? 'Запись подтверждена.' : 'Запись отменена.';
    $buttons = $slot['state'] === 'booked' ? [[
        ['text' => 'Отменить', 'callback_data' => 'cancel:'.$slot['reservation_id']],
    ]] : [];
}
// Передайте $text и ['inline_keyboard' => $buttons] в sendMessage
// для личного чата $actor. answerCallbackQuery подтверждает само нажатие.

Для показа свободного времени выбирайте строки по resource_id и границам выбранного дня: starts_at >= :from AND starts_at < :to AND starts_at > statement_timestamp() AND (state = 'free' OR (state = 'held' AND hold_until <= statement_timestamp())) ORDER BY starts_at. Границы передавайте с часовым поясом. Подпись кнопки получается из starts_at, а её значение — hold: плюс ID строки.

Начните проверку без Telegram: вызовите bookingAction($db, 101, 'hold', '1'), затем ту же функцию с пользователем 202. Первый получит резерв, второй — null. Повтор от 101 должен вернуть прежний reservation_id. Для проверки реальной конкуренции запустите два процесса с отдельными соединениями. Если уведомление не отправилось, состояние записи остаётся сохранённым: при следующем входе покажите пользователю его held и booked интервалы. Историю отмен храните отдельно до очистки полей слота, если она нужна для отчётности.

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

  • Выберите одинаковое время с двух аккаунтов почти одновременно. Один получит резерв, второй увидит обновлённый список. В БД останется один владелец интервала.

  • Дождитесь окончания резерва, выберите тот же интервал со второго аккаунта и нажмите «Подтвердить» в старом сообщении первого. Состояние нового резерва не изменится.

  • Дважды подтвердите действующий резерв. Бот покажет ту же запись. Затем отмените её и убедитесь, что время снова доступно.

  • Откройте список на границе двух дат и проверьте подпись часового пояса. Если обслуживаете регионы с переводом часов, отдельно проверьте день такого перехода.

CallbackQuery · answerCallbackQuery · Блокировки строк PostgreSQL · Ограничения для диапазонов PostgreSQL