Перейти к содержанию
11 минут чтения
Тема: Практика PHP · Google Sheets API · Заявки

Как сохранять заявки из Telegram-бота в Google Таблицы

Для примера бот собирает имя, телефон и описание задачи, а менеджеры разбирают заявки в Google Таблице. Сначала сохраним подтверждённую заявку в приложении, затем добавим строку через Google Sheets API. Так недоступная таблица не потеряет ответы клиента, а повторная обработка не будет создавать новую заявку.

Отделяем приём заявки от записи в таблицу

Таблица удобна как рабочее представление для небольшой команды. Но не стоит делать её единственным местом хранения заявки в момент webhook: сетевой запрос может задержаться или завершиться без ответа. В приложении сохраняем исходные поля, постоянный request_id и состояние экспорта; отдельный обработчик переносит заявку в Google.

Предполагаются PHP 8.3+, Composer, БД и уже работающий приём обновлений Telegram. Анкета должна закончиться явным подтверждением, после которого появляется запись в leads. Черновые ответы по каждому шагу в таблицу не отправляем. Сам диалог можно построить по руководству о пошаговой анкете.

Сразу после транзакции бот сообщает «Заявка принята» и её номер. Формулировка «Заявка добавлена в таблицу» допустима только после подтверждённой записи Google. Во время сбоя менеджеры могут увидеть состояние экспорта в вашем приложении, а клиент не должен заново заполнять анкету.

Дальше показаны реальный вызов append и алгоритм обработки его результата. HTTP-приёмник Telegram и конкретная реализация очереди не входят в этот небольшой пример: используйте уже существующие компоненты приложения.

Даём приложению доступ к одной таблице

Для собственной таблицы команды подходит сервисный аккаунт. Создайте Google Cloud project, включите Google Sheets API и создайте сервисный аккаунт по официальной инструкции Google. Его адрес из поля client_email добавьте в доступ к нужной таблице с правом редактирования. Само включение API не даёт доступа к файлу.

API key не заменяет такую авторизацию для записи приватной таблицы. Если бот должен работать с таблицами разных пользователей, выбирающих свои файлы, понадобится пользовательский OAuth и соответствующий процесс согласия. Domain-wide delegation для обычной общей таблицы в этом сценарии не нужна.

Для примера используем JSON-ключ сервисного аккаунта. Храните его вне public, вне Git и отдельно от JSON-пакетов статей. Дайте чтение только пользователю приложения. Если инфраструктура поддерживает доступ без долгоживущего ключа, используйте её механизм учётных данных; публиковать таблицу «для всех по ссылке» ради бота не требуется.

Подготовьте лист Leads. В первой строке задайте заголовки A:F: request_id, created_at_utc, telegram_user_id, name, phone, task. Не смешивайте эти столбцы с декоративными блоками и промежуточными итогами. Менеджеры могут пользоваться фильтрами и отдельным листом отчёта, сохраняя структуру листа выгрузки.

Из URL вида https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit берётся spreadsheetId. Число gid — идентификатор вкладки, оно не заменяет ID всей таблицы. Имя вкладки понадобится в диапазоне A1: в нашем случае это 'Leads'!A:F.

Устанавливаем PHP-клиент и задаём окружение

Bash · в вашем PHP-приложении
composer require google/apiclient

Задайте GOOGLE_APPLICATION_CREDENTIALS как абсолютный путь к JSON-ключу и GOOGLE_SHEETS_ID как ID таблицы в окружении процесса worker. В обычном PHP наличие .env-файла ещё не загружает переменные: используйте штатный bootstrap приложения либо настоящее окружение процесса. Следующий файл читает именно getenv.

В Laravel положите значения в config/services.php через env и дальше читайте config. Проверьте, что окружение веб-процесса и worker совпадает: частая ситуация — проверка из консоли успешна, а фоновый процесс не видит ключ или не имеет прав на файл.

Официальный Google API PHP Client поддерживает Application Default Credentials. Сервис ниже использует этот механизм и не содержит секретов. Не выводите объект клиента, ключ или Authorization в отладочные журналы.

Добавляем строку с фиксированным порядком полей

Сохраните класс в src/LeadSheet.php и подключите его через ваш автозагрузчик либо require. Метод принимает уже проверенные поля сохранённой заявки, а не сырой update. Все шесть значений передаём строками: длинный Telegram ID, телефон с плюсом и текст не должны преобразовываться в число или формулу.

PHP · src/LeadSheet.php
<?php
declare(strict_types=1);

use Google\Service\Sheets;
use Google\Service\Sheets\ValueRange;

final class LeadSheet
{
    public function __construct(
        private readonly Sheets $sheets,
        private readonly string $spreadsheetId,
    ) {}

    public function append(
        string $requestId, string $createdAtUtc, string $telegramUserId,
        string $name, string $phone, string $task,
    ): string {
        $body = new ValueRange([
            'majorDimension' => 'ROWS',
            'values' => [[$requestId, $createdAtUtc, $telegramUserId, $name, $phone, $task]],
        ]);
        $response = $this->sheets->spreadsheets_values->append(
            $this->spreadsheetId,
            "'Leads'!A:F",
            $body,
            ['valueInputOption' => 'RAW', 'insertDataOption' => 'INSERT_ROWS'],
        );
        $updates = $response->getUpdates();
        $range = $updates?->getUpdatedRange();
        if ($updates?->getUpdatedRows() !== 1 || !is_string($range) || $range === '') {
            throw new RuntimeException('Не получено подтверждение записи строки');
        }
        return $range;
    }
}
PHP · bootstrap экспорта, например worker.php
<?php
declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';
require __DIR__.'/src/LeadSheet.php';

$spreadsheetId = getenv('GOOGLE_SHEETS_ID');
$credentialsPath = getenv('GOOGLE_APPLICATION_CREDENTIALS');
if ($spreadsheetId === false || $spreadsheetId === ''
    || $credentialsPath === false || !is_readable($credentialsPath)) {
    throw new RuntimeException('Проверьте настройки Google Sheets');
}
$client = new Google\Client();
$client->useApplicationDefaultCredentials();
$client->addScope(Google\Service\Sheets::SPREADSHEETS);
$client->setHttpClient(new GuzzleHttp\Client(['connect_timeout' => 3, 'timeout' => 15]));
// Решение о повторе принимает приложение после разбора результата.
$client->setConfig('retry', ['retries' => 0]);
$exporter = new LeadSheet(new Google\Service\Sheets($client), $spreadsheetId);
// Дальше worker загружает одну сохранённую заявку и вызывает $exporter->append(...).

append ищет логическую таблицу в заданном диапазоне и дописывает строку после её конца; диапазон A:F не означает «всегда начинай с A2». Поэтому отдельный аккуратный лист важнее попытки угадать следующий номер строки. Результат updatedRange, например Leads!A12:F12, сохраните в журнале экспорта.

Параметр majorDimension=ROWS задаёт ориентацию массива. valueInputOption=RAW управляет интерпретацией значений. В этом режиме пользовательский текст =1+1 записывается как текст, а не вычисляется. Это также помогает сохранить +79990000000 и ведущие нули. Различие режимов описано в ValueInputOption.

Не добавляйте parse_mode Telegram и HTML-экранирование к полям таблицы. Это другой формат данных. Проверяйте длину и состав полей на уровне анкеты; не передавайте в таблицу весь update вместе с лишними персональными данными.

Создаём постоянный ID и задание экспорта

В момент подтверждения анкеты один раз сгенерируйте request_id, например bin2hex(random_bytes(16)), и сохраните с заявкой. Повтор webhook должен найти ту же заявку по ключу подтверждения, а не создать новый случайный ID. Номер строки в Google не подходит на роль ID: менеджер может отсортировать или переместить строки.

В локальной БД заведите sheet_exports: request_id с UNIQUE, state, attempts, next_attempt_at, updated_range и last_error_code. Создание leads и pending-экспорта выполняйте одной транзакцией; worker подбирает pending после commit. Если используете очередь, одно только dispatch после commit оставляет окно сбоя, поэтому периодический подбор pending полезен как восстановление.

Worker атомарно захватывает pending и переводит в sending, затем вызывает append с данными существующей leads. Успешный ответ переводит экспорт в sent с updated_range. Второй worker, повторное задание или повтор подтверждения не должны повторно захватывать sent/sending. Это не заменяет разбор неизвестного результата внешнего API.

Для одной таблицы удобно обрабатывать экспорт последовательно. Не давайте менеджерам менять request_id в первом столбце: он нужен для поиска уже записанной заявки. Изменение порядка столбцов требует обновления маппинга и теста, иначе телефон и описание задачи незаметно поменяются местами.

Разбираем сбой до повторного append

Если Google вернул 400, проверьте диапазон, имя вкладки и структуру values. Для 401 проверьте механизм авторизации. При 403 сначала выясните причину: недостаточные права, выключенный API, политика Workspace или квота требуют разных действий. Не повторяйте бесконечно запрос с неверным доступом.

При явном отказе из-за квоты, в частности 429, запланируйте ограниченное число повторов с увеличением интервала и случайным разбросом. Не держите webhook открытым через sleep. Принципы backoff и квоты описаны в лимитах Sheets API. Сохраняйте технический код ошибки без текста заявки и учётных данных.

Таймаут, обрыв соединения или серверная ошибка могут оставить результат неизвестным: строка могла добавиться до потери ответа. У append нет вашего уникального ключа запроса, который Google проверяет как ограничение БД. request_id в ячейке нужен для сверки, но сам по себе не предотвращает повторную строку.

В такой ситуации установите state=unknown. Последовательный обработчик или оператор ищет request_id в первом столбце через spreadsheets.values.get. Если строка найдена один раз, отметьте sent и сохраните её диапазон. Если найдена несколько раз, разберите дубли. Если не найдена, не считайте это мгновенным доказательством отказа: исходный запрос ещё мог выполняться. Дождитесь завершения неопределённой операции и повторите сверку до решения о новом append.

Проверка «сначала прочитать столбец, потом append» без сериализации тоже не даёт уникальности: два worker могут одновременно не увидеть ID. Автоматический повтор unknown допустим только при выбранной и понятной политике риска дублей. Для более строгой синхронизации можно выделять фиксированную строку в БД и использовать values.update, но тогда менеджеры не должны перемещать строки листа выгрузки.

Проверяем интеграцию на отдельном листе

  • Запишите тестовую заявку с постоянным request_id и убедитесь, что все шесть значений попали в нужные столбцы.

  • Проверьте телефон с плюсом и ведущими нулями, длинный Telegram ID и строку =1+1. Значения должны остаться текстом.

  • Повторно доставьте подтверждение анкеты: новая leads и второй pending-экспорт появляться не должны.

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

  • Смоделируйте потерю ответа после записи: экспорт должен попасть в unknown, после сверки request_id — в sent, без слепого повторного append.

Доступ менеджеров к таблице и срок хранения заявок настройте по потребностям команды. Телефон и описание задачи нужны не всем участникам организации. Не отправляйте JSON-ключ в Telegram и не прикладывайте его к сообщениям об ошибке.

BotGate может обслуживать Telegram-часть: входящие обновления и отправку ответа клиенту. Доступ к Google, таблица и состояния экспорта остаются в вашем приложении; Telegram API-шлюз не выполняет append вместо Google Sheets API. Подключение Telegram описано в документации BotGate, формат записи — в справочнике spreadsheets.values.append.