Принимаем голосовое сообщение и сохраняем задачу
В обработчике обновлений Telegram найдите message.voice. Сохраните file_id, длительность и file_size, если он пришёл. Для этого сценария принимайте сообщения в личном чате. Сохраните владельца из message.from.id, ID чата и ID сообщения, чтобы вернуть черновик тому же пользователю.
Проверяйте подлинность входящего обновления. Сохраняйте задачу до успешного ответа вебхука. Уникальность по (bot_id, chat_id, message_id) защищает от второй задачи при повторе обновления. file_unique_id может повторяться для одного файла. Для скачивания нужен file_id.
До отправки аудио объясните пользователю, что запись передаётся в SpeechKit. Предложите написать обращение текстом. Ограничьте доступ к аудио и черновикам, задайте срок хранения и удаляйте временные файлы после обработки.
Скачиваем аудио и определяем формат
Вызовите
getFileсfile_id. Возьмитеresult.file_pathи скачайте файл сhttps://api.telegram.org/file/bot<token>/<file_path>. Если ссылка истекла, повторитеgetFile. Исключите URL с токеном из журналов.Для облачного Bot API учитывайте лимит скачивания 20 МБ. Установите свой предел и контролируйте фактический объём при потоковой записи. Если файл не помещается, остановите скачивание и предложите более короткую запись.
Сохраняйте звук во временный приватный файл. Определяйте контейнер, кодек и число каналов по содержимому, например через
ffprobe. Поля MIME и размер в обновлении могут отсутствовать. Для примеров ниже подготовьте Ogg с кодеком Opus. Другой формат преобразуйте локально либо направьте в подходящий режим SpeechKit.
Файл, отправленный как музыка или вложение, может прийти в message.audio или message.document. Такой ввод подключайте отдельно с собственной проверкой. Загрузку файлов разбирает руководство по getFile.
Сохраняем состояние обработки записи
Пользователь может отправить вторую запись, пока первая распознаётся. Поэтому у каждой записи должна быть собственная задача. Храните в ней источник, владельца, путь к скачанному файлу, выбранный режим распознавания, ID внешней операции и состояние.
{
"id": "voice-142",
"bot_id": 1,
"chat_id": 123456789,
"message_id": 842,
"telegram_user_id": 123456789,
"status": "downloaded",
"recognition_mode": "async_v3",
"operation_id": null,
"draft_version": 0
}
Используйте понятные переходы состояний. received означает, что обновление сохранено, downloaded — файл проверен и готов к распознаванию, recognizing — внешняя операция уже запущена. После получения текста переходите в review, а после подтверждения пользователем — в confirmed. Для ошибок храните отдельную причину и время следующей попытки.
Воркер должен атомарно захватывать задачу перед работой. Повторная доставка задания сначала проверяет её состояние. Если текст уже готов, повторно скачивать и распознавать запись не нужно. Если сохранён operation_id, продолжайте опрос этой операции. Если пользователь уже подтвердил обращение, повторный воркер завершает работу.
Ответ «Запись получена, готовлю текст» отправляйте после сохранения задачи. При долгой обработке покажите пользователю статус и возможность написать текст вручную. Если он выбрал ручной ввод, отметьте задачу отменённой для диалога. Поздний результат распознавания должен сохранить этот выбор и не заменить введённый текст.
Распознаём короткую запись синхронно
REST API v1 подходит для одноканального файла до 30 секунд и до 1 МБ. В примере распознаём русскую речь. Получите API-ключ сервисного аккаунта с ролью ai.speechkit-stt.user и передайте его из серверной конфигурации.
use Illuminate\Support\Facades\Http;
function recognizeShortVoice(string $ogg, string $apiKey): string
{
$response = Http::withHeaders(['Authorization' => 'Api-Key '.$apiKey])
->connectTimeout(5)
->timeout(25)
->withBody($ogg, 'application/octet-stream')
->post('https://stt.api.cloud.yandex.net/speech/v1/stt:recognize?lang=ru-RU&format=oggopus');
$text = $response->json('result');
if (!$response->successful() || !is_string($text)) {
throw new RuntimeException('SpeechKit не вернул текст.');
}
return trim($text);
}
Передайте в функцию байты проверенного файла. Endpoint принимает бинарное тело. При пустом результате предложите повторить запись или написать текст. Ошибку формата и отказ доступа обрабатывайте отдельно от временного сбоя сети. Запускайте этот код в очереди, чтобы вебхук ответил после сохранения задачи.
Обрабатываем длинные записи отдельной операцией
Если запись выходит за пределы v1, используйте асинхронный REST API v3. В примере передаём Ogg Opus в content как Base64. Для более крупных файлов SpeechKit поддерживает uri из Yandex Object Storage. Сверьте лимиты для способа передачи и учитывайте память под Base64 и JSON.
{
"content": "<BASE64_АУДИО>",
"recognitionModel": {
"model": "general",
"audioFormat": {
"containerAudio": { "containerAudioType": "OGG_OPUS" }
}
}
}
Отправьте запрос на
https://stt.api.cloud.yandex.net/stt/v3/recognizeFileAsyncс JSON-телом и заголовками Authorization: Api-Key <ключ> и x-folder-id: <каталог>. Используйте те же заголовки при чтении статуса и результата. Сохранитеidоперации рядом с исходным сообщением. Для Object Storage передайтеuriвместоcontentи настройте доступ сервисного аккаунта к приватному бакету.Отдельной задачей проверьте состояние через
GET https://operation.api.cloud.yandex.net/operations/{id}. Пока операция выполняется, планируйте проверку с паузой. Послеdone: trueпроверьте, есть ли ошибка.При успехе вызовите
GET /stt/v3/getRecognition?operation_id={id}наstt.api.cloud.yandex.net. Соберите финальные сегменты по порядку. Если пришёлfinalRefinement, замените им соответствующий финальный сегмент по индексу.
При повторе задания с известным ID продолжайте проверять ту же операцию. Если ответ на запуск потерян до сохранения ID, отметьте исход как неизвестный. Повторный POST может запустить вторую платную операцию. При сбое получения статуса или результата повторяйте чтение с паузами и общим сроком ожидания.
Запускаем и читаем длинную запись из Laravel
Для примера ограничим вход одним каналом Ogg Opus и размером 8 МиБ — это ограничение нашего приложения, не полный лимит SpeechKit. Перед вызовом проверьте длительность и формат файла. Функции ниже запускают одну операцию и читают её результат. Входящий webhook по-прежнему только сохраняет задачу.
<?php
use Illuminate\Support\Facades\Http;
function speechRequest(string $apiKey, string $folderId): \Illuminate\Http\Client\PendingRequest
{
return Http::withHeaders(['Authorization' => 'Api-Key '.$apiKey, 'x-folder-id' => $folderId])
->connectTimeout(5)->timeout(30)->withOptions(['allow_redirects' => false]);
}
function startLongVoice(string $ogg, string $apiKey, string $folderId): string
{
if ($ogg === '' || strlen($ogg) > 8 * 1024 * 1024) {
throw new InvalidArgumentException('Учебный пример принимает до 8 МиБ');
}
$response = speechRequest($apiKey, $folderId)->post(
'https://stt.api.cloud.yandex.net/stt/v3/recognizeFileAsync', [
'content' => base64_encode($ogg),
'recognitionModel' => [
'model' => 'general',
'audioFormat' => ['containerAudio' => ['containerAudioType' => 'OGG_OPUS']],
'languageRestriction' => ['restrictionType' => 'WHITELIST', 'languageCode' => ['ru-RU']],
],
]
);
$id = $response->json('id');
if (!$response->successful() || !is_string($id) || $id === '') {
throw new RuntimeException('Не получен ID операции распознавания');
}
return $id;
}
// Разбирает последовательность JSON-объектов, включая многострочные объекты.
function speechEvents(string $body): iterable
{
$depth = 0; $start = 0; $quoted = false; $escaped = false;
for ($i = 0, $length = strlen($body); $i < $length; $i++) {
$char = $body[$i];
if ($depth === 0) {
if (ctype_space($char)) continue;
if ($char !== '{') throw new RuntimeException('Неожиданный формат результата');
$start = $i;
}
if ($quoted) {
if ($escaped) $escaped = false;
elseif ($char === '\\') $escaped = true;
elseif ($char === '"') $quoted = false;
} elseif ($char === '"') $quoted = true;
elseif ($char === '{') $depth++;
elseif ($char === '}') {
$depth--;
if ($depth === 0) yield json_decode(substr($body, $start, $i - $start + 1), true, 64, JSON_THROW_ON_ERROR);
}
}
if ($depth !== 0 || $quoted) throw new RuntimeException('Результат оборван');
}
function speechText(iterable $events): string
{
$segments = []; $refined = []; $channels = [];
foreach ($events as $event) {
if (isset($event['error'])) throw new RuntimeException('Ошибка потока распознавания');
$item = $event['result'] ?? $event;
$isRefined = isset($item['finalRefinement']);
$final = $isRefined ? ($item['finalRefinement']['normalizedText'] ?? null) : ($item['final'] ?? null);
if (!is_array($final)) continue;
$index = $isRefined ? ($item['finalRefinement']['finalIndex'] ?? null)
: ($item['audioCursors']['finalIndex'] ?? null);
if (!is_scalar($index) || !ctype_digit((string) $index) || strlen((string) $index) > 9) {
throw new RuntimeException('Не получен индекс сегмента');
}
$text = $final['alternatives'][0]['text'] ?? null;
if (!is_string($text)) throw new RuntimeException('Не получен текст сегмента');
$channel = (string) ($final['channelTag'] ?? $item['channelTag'] ?? '0');
$channels[$channel] = true;
if (count($channels) > 1) throw new RuntimeException('Пример рассчитан на один канал');
if ($isRefined || !isset($refined[$index])) $segments[$index] = trim($text);
if ($isRefined) $refined[$index] = true;
}
ksort($segments, SORT_NUMERIC);
return trim(implode("\n", $segments));
}
function readLongVoice(string $operationId, string $apiKey, string $folderId): ?string
{
$response = speechRequest($apiKey, $folderId)->get(
'https://operation.api.cloud.yandex.net/operations/'.rawurlencode($operationId)
);
$state = $response->json();
if (!$response->successful() || !is_array($state) || ($state['id'] ?? null) !== $operationId) {
throw new RuntimeException('Не удалось проверить операцию');
}
if (($state['done'] ?? false) !== true) return null;
if (isset($state['error'])) throw new RuntimeException('Операция распознавания завершилась ошибкой');
$result = speechRequest($apiKey, $folderId)->get(
'https://stt.api.cloud.yandex.net/stt/v3/getRecognition', ['operation_id' => $operationId]
);
if (!$result->successful()) throw new RuntimeException('Не удалось получить результат');
return speechText(speechEvents($result->body()));
}
Сохраните код, например, в app/Support/speechkit.php и подключите его через require_once в задании. apiKey и folderId передавайте из серверной конфигурации. Первый запуск вызывает startLongVoice($ogg, $apiKey, $folderId) и сразу сохраняет возвращённый operation_id. Для уже запущенной задачи вызывайте только readLongVoice($operationId, $apiKey, $folderId).
null означает, что результат ещё не готов: поставьте следующую проверку с задержкой, например через 10 секунд. Строка означает завершение распознавания; пустую строку обработайте как отсутствие распознанной речи. Сохраните текст и переведите задачу в review одной транзакцией, только если пользователь ещё не отменил распознавание. Не держите воркер в бесконечном цикле ожидания.
Ответ getRecognition содержит поток JSON-событий. В примере speechEvents разбирает отдельные объекты, а speechText выбирает финальные сегменты, сортирует их и заменяет уточнёнными версиями. Скобки внутри распознанной речи не считаются границами JSON. Для больших файлов читайте ответ потоково и ограничивайте память; здесь результат небольшого голосового целиком находится в памяти.
Проверьте сборку без платного запроса: передайте в speechText два события final с индексами 1 и 0 и событие finalRefinement для индекса 0. Текст должен идти в порядке 0, 1 и содержать уточнённую версию первого сегмента один раз. Отдельно проверьте оборванный JSON и ошибку API. Исключение при чтении допускает повтор чтения; исключение при запуске требует учёта неизвестного исхода, чтобы не оплачивать вторую операцию вслепую.
Разбираем ошибки и ограничиваем ожидание
Для каждого этапа задайте свой предел ожидания. Скачивание ограничивается временем и объёмом, запрос распознавания — сетевым таймаутом, асинхронная задача — общим сроком ожидания результата. Значения выбирайте под допустимую длину записи и нагрузку сервиса. Покажите пользователю сообщение, если этот срок закончился.
Неверный формат. Сверьте кодек и число каналов с выбранным API. Одно переименование расширения не преобразует звук. При конвертации сохраняйте исходный файл до проверки результата.
Отказ доступа. Проверьте ключ, роль сервисного аккаунта и каталог. Повтор запроса с той же неверной настройкой только увеличит очередь ошибок.
Временная недоступность. Назначьте повтор чтения с увеличивающейся паузой и ограничением числа попыток. Для потерянного ответа на запуск внешней операции сначала учитывайте неизвестный исход.
Пустой или бессмысленный текст. Сообщите, что запись не удалось разобрать. Предложите более короткое сообщение в тихом месте или ручной ввод.
В журнале достаточно ID задачи, этапа, безопасного кода ошибки и длительности. Аудио, полный текст обращения и ключ доступа не должны попадать в технический журнал по умолчанию. Срок удаления исходной записи считайте отдельно от срока хранения подтверждённого обращения.
Показываем черновик и принимаем правки
Отправьте расшифровку в личный чат без parse_mode, чтобы текст воспринимался буквально. Длинный результат разбейте по границам абзацев с учётом лимита Telegram или приложите текстовый файл. Добавьте кнопки «Подтвердить» и «Исправить».
В callback_data передавайте короткий ID черновика, а владельца проверяйте по callback_query.from.id. Для исправления попросите ответить на конкретное сообщение с приглашением. Свяжите ответ с ID черновика, чатом и пользователем. Так два голосовых, отправленные подряд, смогут обрабатываться независимо.
Подтверждение переводит черновик в итоговую заявку и сохраняет отредактированный текст в одной транзакции. Уникальный ключ по ID черновика защищает от повторного создания обращения.
Например, клиент продиктовал «Не приходит код входа на второй телефон». Бот показывает текст и предлагает подтвердить или исправить. По кнопке «Исправить» он просит прислать весь исправленный текст ответом на новое сообщение. Такой вариант удобнее для первой реализации, чем распознавание команд «замени второе слово».
У черновика храните номер версии. После правки увеличьте его и обновите кнопки подтверждения. Если пользователь нажал «Подтвердить» в старом сообщении, покажите актуальную версию и попросите подтвердить её. Это защищает от отправки первоначальной расшифровки после того, как пользователь уже внёс исправления.
Проверяем короткий, длинный и неразборчивый звук
Отправьте короткую запись с именем и номером. Исправьте строку и убедитесь, что в заявку попала исправленная версия.
Отправьте запись длиннее 30 секунд. После перезапуска воркера проверка должна продолжиться по сохранённому ID операции.
Повторите доставку обновления и подтверждение черновика. Должны остаться по одной задаче распознавания и заявке.
Проверьте тишину, неподходящий формат и отсутствие доступа к SpeechKit. Бот должен предложить следующий шаг, а черновик не должен автоматически попасть в поддержку.
Voice и getFile в Telegram Bot API · Синхронный API SpeechKit · Асинхронный запуск и результат · Поля AsyncRecognizer v3