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

Телефония

Дайте VibeOS телефонные возможности без изменения основных инструментов. Предоставьте и сохраните номер Twilio, отправляйте и получайте SMS/MMS, совершайте прямые звонки и размещайте AI-управляемые исходящие звонки через Bland.ai или Vapi.

Метаданные навыка​

ИсточникОпционально — установка через vibeos skills install official/productivity/telephony
Путьoptional-skills/productivity/telephony
Версия1.0.0
АвторNous Research
ЛицензияMIT
Платформыlinux, macos, windows
Тегиtelephony, phone, sms, mms, voice, twilio, bland.ai, vapi, calling, texting
Связанные навыкиmaps, google-workspace, agentmail

Справочник: полный SKILL.md​

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при активации этого навыка. Это то, что агент видит в качестве инструкций, когда навык активен.

Телефония — номера, звонки и тексты без изменения основных инструментов

Этот опциональный навык даёт VibeOS практические телефонные возможности, оставляя телефонию вне списка основных инструментов.

Он поставляется со вспомогательным скриптом scripts/telephony.py, который может:

  • сохранять учётные данные провайдера в ${VIBEOS_HOME:-~/.vibeos}/.env
  • искать и покупать номер Twilio
  • запоминать этот номер для последующих сессий
  • отправлять SMS/MMS с сохранённого номера
  • опрашивать входящие SMS для этого номера без необходимости в вебхук-сервере
  • совершать прямые звонки Twilio с использованием TwiML <Say> или <Play>
  • импортировать сохранённый номер Twilio в Vapi
  • размещать исходящие AI-звонки через Bland.ai или Vapi

Что это решает​

Этот навык предназначен для покрытия практических телефонных задач, которые действительно нужны пользователям:

  • исходящие звонки
  • отправка текстов
  • владение переиспользуемым номером агента
  • проверка сообщений, приходящих на этот номер позже
  • сохранение номера и связанных ID между сессиями
  • дружественная к будущему телефонная идентичность для опроса входящих SMS и других автоматизаций

Он не превращает VibeOS в шлюз для входящих звонков в реальном времени. Входящие SMS обрабатываются путём опроса Twilio REST API. Этого достаточно для многих рабочих процессов, включая уведомления и получение одноразовых кодов, без добавления инфраструктуры вебхуков.

Правила безопасности — обязательны​

  1. Всегда подтверждайте перед совершением звонка или отправкой текста.
  2. Никогда не набирайте экстренные номера.
  3. Никогда не используйте телефонию для преследования, спама, выдачи себя за другого или любых незаконных действий.
  4. Относитесь к сторонним телефонным номерам как к чувствительным операционным данным:
    • не сохраняйте их в памяти VibeOS
    • не включайте их в документацию навыка, сводки или последующие заметки, если пользователь явно этого не хочет
  5. Допускается сохранять номер Twilio, принадлежащий агенту, так как это часть конфигурации пользователя.
  6. VoIP-номера не гарантируют работу со всеми сторонними 2FA-процессами. Используйте с осторожностью и чётко устанавливайте ожидания пользователя.

Дерево решений — какой сервис использовать?​

Используйте эту логику вместо жёстко заданной маршрутизации провайдера:

1) «Я хочу, чтобы у VibeOS был собственный реальный номер телефона»​

Используйте Twilio.

Почему:

  • самый простой путь к покупке и сохранению номера
  • лучшая поддержка SMS/MMS
  • самая простая история опроса входящих SMS
  • самый чистый будущий путь к входящим вебхукам или обработке звонков

Сценарии использования:

  • получать тексты позже
  • отправлять оповещения о развёртывании / уведомления по cron
  • поддерживать переиспользуемую телефонную идентичность для агента
  • экспериментировать с телефонными auth-процессами позже

2) «Мне нужен только самый простой исходящий AI-звонок прямо сейчас»​

Используйте Bland.ai.

Почему:

  • самая быстрая настройка
  • один API-ключ
  • не нужно сначала покупать/импортировать номер самостоятельно

Компромисс:

  • менее гибкий
  • качество голоса приемлемое, но не лучшее

3) «Я хочу лучшее качество голоса для разговорного AI»​

Используйте Twilio + Vapi.

Почему:

  • Twilio даёт вам собственный номер
  • Vapi обеспечивает лучшее качество разговорного AI и больше гибкости в голосе/моделях

Рекомендуемый поток:

  1. Купить/сохранить номер Twilio
  2. Импортировать его в Vapi
  3. Сохранить полученный VAPI_PHONE_NUMBER_ID
  4. Использовать ai-call --provider vapi

4) «Я хочу позвонить с пользовательским предварительно записанным голосовым сообщением»​

Используйте прямой звонок Twilio с публичным URL аудио.

Почему:

  • самый простой способ воспроизвести пользовательский MP3
  • хорошо сочетается с text_to_speech от VibeOS плюс публичный хост файлов или туннель

Файлы и постоянное состояние​

Навык сохраняет состояние телефонии в двух местах:

${VIBEOS_HOME:-~/.vibeos}/.env​

Используется для долгоживущих учётных данных провайдера и ID сохранённых номеров, например:

  • TWILIO_ACCOUNT_SID
  • TWILIO_AUTH_TOKEN
  • TWILIO_PHONE_NUMBER
  • TWILIO_PHONE_NUMBER_SID
  • BLAND_API_KEY
  • VAPI_API_KEY
  • VAPI_PHONE_NUMBER_ID
  • PHONE_PROVIDER (провайдер AI-звонков: bland или vapi)

~/.vibeos/telephony_state.json​

Используется для состояния, относящегося только к навыку, которое должно сохраняться между сессиями, например:

  • запомненный номер Twilio по умолчанию / SID
  • запомненный ID номера телефона Vapi
  • последний SID/дата входящего сообщения для контрольных точек опроса входящих

Это означает:

  • при следующей загрузке навыка diagnose может сообщить, какой номер уже настроен
  • twilio-inbox --since-last --mark-seen может продолжить с предыдущей контрольной точки

Найдите вспомогательный скрипт​

После установки этого навыка найдите скрипт следующим образом:

SCRIPT="$(find ~/.vibeos/skills -path '*/telephony/scripts/telephony.py' -print -quit)"

Если SCRIPT пуст, навык ещё не установлен.

Установка​

Это официальный опциональный навык, поэтому установите его из Skills Hub:

vibeos skills search telephony
vibeos skills install official/productivity/telephony

Настройка провайдера​

Twilio — собственный номер, SMS/MMS, прямые звонки, опрос входящих SMS​

Зарегистрируйтесь на:

Затем сохраните учётные данные в VibeOS:

python3 "$SCRIPT" save-twilio ACXXXXXXXXXXXXXXXXXXXXXXXXXXXX your_auth_token_here

Поиск доступных номеров:

python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 5

Покупка и запоминание номера:

python3 "$SCRIPT" twilio-buy "+17025551234" --save-env

Список принадлежащих номеров:

python3 "$SCRIPT" twilio-owned

Установка одного из них как номера по умолчанию позже:

python3 "$SCRIPT" twilio-set-default "+17025551234" --save-env
# или
python3 "$SCRIPT" twilio-set-default PNXXXXXXXXXXXXXXXXXXXXXXXXXXXX --save-env

Bland.ai — самый простой исходящий AI-звонок​

Зарегистрируйтесь на:

Сохраните конфигурацию:

python3 "$SCRIPT" save-bland your_bland_api_key --voice mason

Vapi — лучшее качество разговорного голоса​

Зарегистрируйтесь на:

Сначала сохраните API-ключ:

python3 "$SCRIPT" save-vapi your_vapi_api_key

Импортируйте ваш номер Twilio в Vapi и сохраните полученный ID номера телефона:

python3 "$SCRIPT" vapi-import-twilio --save-env

Если вы уже знаете ID номера телефона Vapi, сохраните его напрямую:

python3 "$SCRIPT" save-vapi your_vapi_api_key --phone-number-id vapi_phone_number_id_here

Диагностика текущего состояния​

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

python3 "$SCRIPT" diagnose

Используйте это в первую очередь при возобновлении работы в последующей сессии.

Типовые рабочие процессы​

A. Купить номер агента и продолжать использовать его позже​

  1. Сохраните учётные данные Twilio:
python3 "$SCRIPT" save-twilio AC... auth_token_here
  1. Найдите номер:
python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 10
  1. Купите его и сохраните в ${VIBEOS_HOME:-~/.vibeos}/.env + состояние:
python3 "$SCRIPT" twilio-buy "+17025551234" --save-env
  1. В следующей сессии выполните:
python3 "$SCRIPT" diagnose

Это покажет запомненный номер по умолчанию и состояние контрольной точки входящих.

B. Отправить текст с номера агента​

python3 "$SCRIPT" twilio-send-sms "+15551230000" "Your deployment completed successfully."

С медиа:

python3 "$SCRIPT" twilio-send-sms "+15551230000" "Here is the chart." --media-url "https://example.com/chart.png"

C. Проверить входящие тексты позже без вебхук-сервера​

Опрос входящих для номера Twilio по умолчанию:

python3 "$SCRIPT" twilio-inbox --limit 20

Показать только сообщения, поступившие после последней контрольной точки, и продвинуть контрольную точку после прочтения:

python3 "$SCRIPT" twilio-inbox --since-last --mark-seen

Это основной ответ на вопрос «как мне получить доступ к сообщениям, которые номер получает при следующей загрузке навыка?»

D. Совершить прямой звонок Twilio со встроенным TTS​

python3 "$SCRIPT" twilio-call "+15551230000" --message "Hello! This is VibeOS calling with your status update." --voice Polly.Joanna

E. Позвонить с предварительно записанным / пользовательским голосовым сообщением​

Это основной путь для повторного использования существующей поддержки text_to_speech от VibeOS.

Используйте это, когда:

  • вы хотите, чтобы звонок использовал настроенный голос TTS от VibeOS, а не Twilio <Say>
  • вам нужна однонаправленная голосовая доставка (брифинг, оповещение, шутка, напоминание, обновление статуса)
  • вам не нужен живой разговорный телефонный звонок

Сгенерируйте или разместите аудио отдельно, затем:

python3 "$SCRIPT" twilio-call "+155****0000" --audio-url "https://example.com/briefing.mp3"

Рекомендуемый рабочий процесс VibeOS TTS -> Twilio Play:

  1. Сгенерируйте аудио с помощью VibeOS text_to_speech.
  2. Сделайте полученный MP3 публично доступным.
  3. Совершите звонок Twilio с --audio-url.

Пример потока агента:

  • Попросите VibeOS создать аудиосообщение с помощью text_to_speech
  • При необходимости опубликуйте файл через временный статический хост / туннель / URL объектного хранилища
  • Используйте twilio-call --audio-url ... для доставки по телефону

Хорошие варианты хостинга для MP3:

  • временный публичный URL объектного/файлового хранилища
  • кратковременный туннель к локальному статическому файловому серверу
  • любой существующий HTTPS URL, который телефонный провайдер может получить напрямую

Важное замечание:

  • VibeOS TTS отлично подходит для предварительно записанных исходящих сообщений
  • Bland/Vapi лучше подходят для живых разговорных AI-звонков, так как они сами обрабатывают стек аудио телефонии в реальном времени
  • VibeOS STT/TTS сам по себе не используется здесь как полноценный двусторонний телефонный разговор; для этого потребовалась бы гораздо более тяжёлая интеграция потоковой передачи/вебхуков, чем этот навык пытается внедрить

F. Навигация по телефонному дереву / IVR с прямым звонком Twilio​

Если вам нужно нажать цифры после соединения, используйте --send-digits. Twilio интерпретирует w как короткое ожидание.

python3 "$SCRIPT" twilio-call "+18005551234" --message "Connecting to billing now." --send-digits "ww1w2w3"

Это полезно для достижения конкретной ветки меню перед передачей человеку или доставкой короткого сообщения о статусе.

G. Исходящий AI-звонок с Bland.ai​

python3 "$SCRIPT" ai-call "+15551230000" "Call the dental office, ask for a cleaning appointment on Tuesday afternoon, and if they do not have Tuesday availability, ask for Wednesday or Thursday instead." --provider bland --voice mason --max-duration 3

Проверка статуса:

python3 "$SCRIPT" ai-status <call_id> --provider bland

Запрос анализа Bland после завершения:

python3 "$SCRIPT" ai-status <call_id> --provider bland --analyze "Was the appointment confirmed?,What date and time?,Any special instructions?"

H. Исходящий AI-звонок с Vapi на вашем номере​

  1. Импортируйте ваш номер Twilio в Vapi:
python3 "$SCRIPT" vapi-import-twilio --save-env
  1. Совершите звонок:
python3 "$SCRIPT" ai-call "+15551230000" "You are calling to make a dinner reservation for two at 7:30 PM. If that is unavailable, ask for the nearest time between 6:30 and 8:30 PM." --provider vapi --max-duration 4
  1. Проверьте результат:
python3 "$SCRIPT" ai-status <call_id> --provider vapi

Рекомендуемая процедура агента​

Когда пользователь запрашивает звонок или текст:

  1. Определите, какой путь соответствует запросу, используя дерево решений.
  2. Выполните diagnose, если состояние конфигурации неясно.
  3. Соберите полные детали задачи.
  4. Подтвердите с пользователем перед набором номера или отправкой текста.
  5. Используйте правильную команду.
  6. При необходимости опросите результаты.
  7. Подведите итог, не сохраняя сторонние номера телефонов в памяти VibeOS.

Что этот навык всё ещё не делает​

  • приём входящих звонков в реальном времени
  • push-уведомления о живых SMS на основе вебхуков в цикл агента
  • гарантированная поддержка произвольных сторонних 2FA-провайдеров

Для этого потребовалось бы больше инфраструктуры, чем для чистого опционального навыка.

Подводные камни​

  • Пробные аккаунты Twilio и региональные правила могут ограничивать, кому вы можете звонить/писать.
  • Некоторые сервисы отклоняют VoIP-номера для 2FA.
  • twilio-inbox опрашивает REST API; это не мгновенная push-доставка.
  • Исходящие звонки Vapi всё ещё зависят от наличия действительного импортированного номера.
  • Bland — самый простой, но не всегда лучший по качеству звука.
  • Не храните произвольные сторонние номера телефонов в памяти VibeOS.

Контрольный список проверки​

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

  1. diagnose показывает готовность провайдера и запомненное состояние
  2. поиск и покупка номера Twilio
  3. сохранение этого номера в ${VIBEOS_HOME:-~/.vibeos}/.env
  4. отправка SMS с принадлежащего номера
  5. опрос входящих текстов для принадлежащего номера позже
  6. совершение прямого звонка Twilio
  7. совершение AI-звонка через Bland или Vapi

Ссылки​