Отделяем приём заявки от записи в таблицу
Таблица удобна как рабочее представление для небольшой команды. Но не стоит делать её единственным местом хранения заявки в момент 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-клиент и задаём окружение
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
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
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.