Перейти к основному контенту

Voice Input — голосовой интерфейс для AI-воронок

Пакет: Voice
Полное имя компонента: Common.Voice.VoiceInput

Что это

Voice Input — это высокоуровневый компонент Metabot для приёма и обработки голосовых сообщений внутри сценариев.

Он позволяет использовать голос как полноценный пользовательский ввод:

  • принять voice / video note / audio;

  • дождаться сообщения пользователя;

  • проверить stop-фразы и ограничения;

  • получить ссылку на аудиофайл от мессенджера;

  • отправить файл в speech-to-text провайдер;

  • вернуть распознанный текст обратно в сценарий;

  • продолжить логику как обычный flow Metabot.

Проще говоря, VoiceInput — это не просто “распознавание речи”.
Это голосовой middleware для conversational runtime.

Зачем нужен Voice Input

Большинство сценариев в ботах до сих пор строятся вокруг текста:

  • кнопки,

  • короткие ответы,

  • поля ввода,

  • ручной набор.

Но в живом использовании это часто неудобно.

Пользователь:

  • идёт по улице;

  • едет в машине;

  • держит телефон одной рукой;

  • не хочет долго печатать;

  • хочет объяснить мысль быстро и по-человечески.

И здесь голосовой ввод даёт очень сильное преимущество.

Что меняется с голосом

Когда человек печатает:

  • мысль дробится;

  • ответы укорачиваются;

  • детали теряются;

  • поток рвётся.

Когда человек говорит:

  • ответ становится быстрее;

  • в нём больше контекста;

  • появляется больше нюансов;

  • сценарий получает более “живой” материал для анализа.

Именно поэтому VoiceInput — это не просто удобство.
Это другой тип интерфейса.

Почему голос — это не просто удобство

Если вы ещё не используете голосовой ввод в сценариях, вы упускаете один из самых сильных интерфейсов взаимодействия с пользователем.

Речь — это не просто альтернатива тексту.
Это другой уровень скорости и качества мышления.

Скорость

  • 🎙 Речь: 120–160 слов в минуту

  • ⌨️ Печать: 25–60 слов в минуту

То есть голос в среднем быстрее печати примерно в 3–5 раз.

Но дело не только в скорости.

Что реально меняется

Когда человек печатает:

  • он подгоняет мысль под форму;

  • упрощает ответ;

  • сокращает детали;

  • тратит усилия на набор.

Когда человек говорит:

  • мысль идёт непрерывно;

  • смысл разворачивается естественно;

  • формулировка рождается “на ходу”;

  • система получает более плотный контекст.

Для AI-сценариев это особенно важно:
чем богаче вход, тем точнее можно:

  • интерпретировать ответ;

  • строить профиль;

  • определять intent;

  • извлекать структуру;

  • формировать полезный результат.

Что это даёт сценаристу и продуктологу

VoiceInput открывает другой класс сценариев.

С ним можно строить не только:

  • анкеты;

  • текстовые квизы;

  • меню и кнопки;

но и:

  • голосовые интервью;

  • профилирование пользователей;

  • глубокую квалификацию;

  • сценарии поддержки “на ходу”;

  • AI-собеседования;

  • входные воронки, где человек говорит свободно.

То есть сценарист перестаёт строить только “дерево ответов”
и начинает строить интерфейс мышления.

Где используется Voice Input

Компонент особенно полезен там, где:

  • пользователь должен отвечать развернуто;

  • неудобно печатать руками;

  • важна скорость ввода;

  • нужно получить больше смысла, чем помещается в короткий текст;

  • дальше ответ будет анализироваться через LLMQuery.

Типовые кейсы:

  • голосовое профилирование;

  • onboarding в экосистему;

  • support-сценарии;

  • intake-интервью;

  • сбор обратной связи;

  • сценарии диагностики;

  • AI-ассистенты в Telegram;

  • мобильные интерфейсы с минимальным трением.

Где находится компонент

Компонент находится в пакете Voice и подключается как обычный плагин Metabot:

const VoiceInput = require("Common.Voice.VoiceInput")

Как работает Voice Input

VoiceInput работает как многошаговый голосовой pipeline, в котором участвуют:

  • сценарий;

  • callback от мессенджера;

  • системный processor script;

  • внешний STT-провайдер;

  • callback с готовым распознанным текстом.

Это важнее, чем кажется.

Если LLMQuery — это двухфазный асинхронный AI-запрос,
то VoiceInput — это уже голосовой pipeline из нескольких фаз, потому что здесь нужно сначала дождаться аудиосообщения, потом получить файл, а потом ещё отдельно дождаться результата распознавания.

Общая схема работы

Сценарий
→ VoiceInput.expect()
→ ожидание голосового сообщения
→ callback от мессенджера
→ получение ссылки на файл
→ отправка в STT
→ callback от STT
→ сохранение текста
→ переход в successScript

Фазы выполнения

Фаза 1. Сценарий включает ожидание голосового ввода

В обычной команде Run JavaScript сценарий вызывает:

VoiceInput.expect({...})

На этом этапе компонент:

  • принимает конфигурацию;

  • сохраняет её как активный voice input;

  • переводит сценарий в режим ожидания;

  • отправляет управление в processor script.

Фаза 2. Пользователь отправляет голосовое сообщение

Дальше processor script через callback-команду ждёт ввод пользователя.

На этом этапе компонент:

  • проверяет, не пришла ли stop-фраза;

  • проверяет тип сообщения;

  • валидирует длительность и размер файла;

  • получает file_id;

  • запрашивает у Telegram ссылку на файл;

  • сохраняет ссылку в sourceAttr.

То есть в этой фазе мы ещё не распознаём текст.
Мы только:

  • понимаем, что пришёл допустимый голосовой артефакт;

  • получаем ссылку на файл;

  • подготавливаем его к отправке в STT.

Фаза 3. Аудио отправляется в speech-to-text

Во второй команде processor script запускается асинхронный API-вызов к STT-провайдеру.

На этом этапе:

  • файл уже известен;

  • компонент формирует STT-запрос;

  • использует провайдера и модель из конфигурации;

  • показывает пользователю сообщение вроде ✅ Принято. Обрабатываю…;

  • уходит в ожидание callback с распознанным текстом.

Фаза 4. Текст возвращается в сценарий

Когда STT-провайдер возвращает результат:

  • текст сохраняется в targetAttr;

  • дополнительные атрибуты из extraAttrs устанавливаются в lead;

  • внутреннее состояние очищается;

  • сценарий переводится в successScript.

После этого распознанный текст можно использовать:

  • как обычный lead-атрибут;

  • передать в LLMQuery;

  • сохранить в профиль;

  • подставить в другой шаг сценария.

Обязательное условие использования

Чтобы VoiceInput работал, в боте должен существовать системный processor script, через который проходят оба callback-цикла.

По умолчанию это скрипт с кодом:

VoiceInput_Processor

Без него компонент работать не будет.

Причина в том, что VoiceInput не ограничивается одним вызовом.
Ему нужен отдельный системный контур, который:

  • обрабатывает callback от мессенджера;

  • потом обрабатывает callback от STT-провайдера.

Как устроен processor script

Processor script должен содержать две команды.

Команда 1. Callback от мессенджера

Тип команды:
Run JavaScript Callback

Код:

const VoiceInput = require("Common.Voice.VoiceInput")

return VoiceInput.onCallback({ lead, isFirstImmediateCall })

Эта команда:

  • ждёт пользовательский ввод;

  • проверяет stop-фразы;

  • определяет, пришёл ли voice / video_note / audio;

  • получает ссылку на файл;

  • сохраняет runtime-контекст для следующего шага.

Команда 2. Callback от STT-провайдера

Тип команды:
Run asynchronous API-request

Код:

const VoiceInput = require("Common.Voice.VoiceInput")

return VoiceInput.onSTT({ lead, isFirstImmediateCall })

Эта команда:

  • инициирует запрос на speech-to-text;

  • ждёт async callback от STT;

  • получает распознанный текст;

  • сохраняет его в targetAttr;

  • переводит сценарий в successScript.

Что важно понимать про processor script

VoiceInput.expect() сам по себе не завершает всю работу.

Он только:

  • включает режим ожидания;

  • сохраняет конфигурацию;

  • передаёт управление в processor script.

Вся дальнейшая механика:

  • ожидание голоса,

  • получение файла,

  • отправка в STT,

  • получение текста

происходит именно через этот системный скрипт.

Поэтому если вы импортируете готовую конфигурацию, processor script уже должен быть внутри.
Если вы собираете решение вручную — его нужно создать обязательно.

Что нужно настроить перед использованием

Перед тем как использовать VoiceInput, нужно убедиться, что настроены:

  • канал,

  • processor script,

  • инфраструктурные атрибуты бота,

  • ключ STT-провайдера.

1. Настройки канала: реакция на аудио и голосовые

Это обязательная настройка.

В канале нужно включить:

  • Реакция на аудио: Штатная (NLP и меню)

  • Реакция на голосовые сообщения: Штатная (NLP и меню)

Иначе голосовые сообщения будут игнорироваться или не будут корректно попадать в сценарий.

Пример

Реакция на аудио:
Штатная (NLP и меню)

Реакция на голосовые сообщения:
Штатная (NLP и меню)

Сейчас компонент ориентирован прежде всего на Telegram-контур.
В дальнейшем этот слой может расширяться и на другие каналы.

2. Инфраструктурные атрибуты бота

Как и в случае с LLMQuery, для callback-механики должны быть настроены:

  • METABOT_API_TOKEN

  • METABOT_SERVER_DOMAIN

Они нужны, потому что callback от внешнего STT-провайдера возвращается обратно в Metabot через внешний процессор.

3. Ключ провайдера speech-to-text

Сам ключ STT обычно передаётся через tokenKey в конфигурации компонента.

Например:

stt: {
  provider: "openai",
  options: { model: "whisper-1", language: "ru" },
  asyncResponse: true,
  tokenKey: "OPENAI_API_KEY"
}

То есть:

  • ключ хранится в атрибуте бота;

  • имя этого атрибута указывается в tokenKey.