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

Настройка SMS (Twilio)

VibeOS подключается к SMS через API Twilio. Люди отправляют сообщения на ваш номер Twilio и получают ответы от ИИ — тот же диалоговый опыт, что и в Telegram или Discord, но через обычные текстовые сообщения.

Общие учётные данные

SMS-шлюз использует общие учётные данные с опциональным навыком телефонии. Если вы уже настроили Twilio для голосовых звонков или разовых SMS, шлюз работает с теми же TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN и TWILIO_PHONE_NUMBER.

Предварительные требования​

  • Аккаунт Twilio — Зарегистрируйтесь на twilio.com (доступна бесплатная пробная версия)
  • Номер телефона Twilio с поддержкой SMS
  • Публично доступный сервер — Twilio отправляет вебхуки на ваш сервер при получении SMS
  • aiohttp — cd ~/.vibeos/vibeos-agent && uv pip install -e ".[sms]"

Шаг 1: Получите учётные данные Twilio​

  1. Перейдите в Консоль Twilio
  2. Скопируйте Account SID и Auth Token с панели управления
  3. Перейдите в Phone Numbers → Manage → Active Numbers — запишите ваш номер телефона в формате E.164 (например, +15551234567)

Шаг 2: Настройте VibeOS​

Интерактивная настройка (рекомендуется)​

vibeos gateway setup

Выберите SMS (Twilio) из списка платформ. Мастер запросит ваши учётные данные.

Ручная настройка​

Добавьте в ~/.vibeos/.env:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=ваш_токен_авторизации
TWILIO_PHONE_NUMBER=+15551234567

# Безопасность: ограничение по конкретным номерам (рекомендуется)
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Опционально: домашний канал для доставки заданий cron
SMS_HOME_CHANNEL=+15559876543

Шаг 3: Настройте вебхук Twilio​

Twilio необходимо знать, куда отправлять входящие сообщения. В Консоли Twilio:

  1. Перейдите в Phone Numbers → Manage → Active Numbers
  2. Нажмите на ваш номер телефона
  3. В разделе Messaging → A MESSAGE COMES IN укажите:
    • Webhook: https://ваш-сервер:8080/webhooks/twilio
    • HTTP Method: POST
Открытие вебхука

Если вы запускаете VibeOS локально, используйте туннель для открытия вебхука:

# Используя cloudflared
cloudflared tunnel --url http://localhost:8080

# Используя ngrok
ngrok http 8080

Укажите полученный публичный URL в качестве вебхука Twilio.

Установите SMS_WEBHOOK_URL равным тому же URL, который вы настроили в Twilio. Это необходимо для проверки подписи Twilio — адаптер откажется запускаться без него:

# Должен совпадать с URL вебхука в вашей Консоли Twilio
SMS_WEBHOOK_URL=https://ваш-сервер:8080/webhooks/twilio

Порт вебхука по умолчанию — 8080. Измените с помощью:

SMS_WEBHOOK_PORT=3000

Шаг 4: Запустите шлюз​

vibeos gateway

Вы должны увидеть:

[sms] Twilio webhook server listening on 127.0.0.1:8080, from: +1555***4567

Если вы видите Refusing to start: SMS_WEBHOOK_URL is required, установите SMS_WEBHOOK_URL равным публичному URL, настроенному в вашей Консоли Twilio (см. Шаг 3).

Отправьте сообщение на ваш номер Twilio — VibeOS ответит через SMS.

Переменные окружения​

ПеременнаяОбязательнаяОписание
TWILIO_ACCOUNT_SIDДаAccount SID Twilio (начинается с AC)
TWILIO_AUTH_TOKENДаAuth Token Twilio (также используется для проверки подписи вебхука)
TWILIO_PHONE_NUMBERДаВаш номер телефона Twilio (формат E.164)
SMS_WEBHOOK_URLДаПубличный URL для проверки подписи Twilio — должен совпадать с URL вебхука в вашей Консоли Twilio
SMS_WEBHOOK_PORTНетПорт прослушивания вебхука (по умолчанию: 8080)
SMS_WEBHOOK_HOSTНетАдрес привязки вебхука (по умолчанию: 127.0.0.1)
SMS_INSECURE_NO_SIGNATUREНетУстановите true для отключения проверки подписи (только для локальной разработки — не для продакшена)
SMS_ALLOWED_USERSНетРазделённые запятыми номера телефонов в формате E.164, которым разрешено общаться
SMS_ALLOW_ALL_USERSНетУстановите true, чтобы разрешить всем (не рекомендуется)
SMS_HOME_CHANNELНетНомер телефона для доставки заданий cron / уведомлений
SMS_HOME_CHANNEL_NAMEНетОтображаемое имя для домашнего канала (по умолчанию: Home)

Особенности работы SMS​

  • Только обычный текст — Markdown автоматически удаляется, так как SMS отображает его как буквальные символы
  • Ограничение в 1600 символов — Длинные ответы разбиваются на несколько сообщений по естественным границам (переносы строк, затем пробелы)
  • Предотвращение эха — Сообщения с вашего собственного номера Twilio игнорируются для предотвращения циклов
  • Сокрытие номеров телефонов — Номера телефонов скрываются в логах для конфиденциальности

Безопасность​

Проверка подписи вебхука​

VibeOS проверяет, что входящие вебхуки действительно исходят от Twilio, путём верификации заголовка X-Twilio-Signature (HMAC-SHA1). Это предотвращает внедрение поддельных сообщений злоумышленниками.

SMS_WEBHOOK_URL обязателен. Установите его равным публичному URL, настроенному в вашей Консоли Twilio. Адаптер откажется запускаться без него.

Для локальной разработки без публичного URL можно отключить проверку:

# Только для локальной разработки — НЕ для продакшена
SMS_INSECURE_NO_SIGNATURE=true

Белые списки пользователей​

Шлюз запрещает всех пользователей по умолчанию. Настройте белый список:

# Рекомендуется: ограничить конкретными номерами
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Или разрешить всех (НЕ рекомендуется для ботов с доступом к терминалу)
SMS_ALLOW_ALL_USERS=true
предупреждение

SMS не имеет встроенного шифрования. Не используйте SMS для чувствительных операций, если вы не понимаете последствия для безопасности. Для чувствительных случаев предпочтительнее Signal или Telegram.

Устранение неполадок​

Сообщения не приходят​

  1. Проверьте, что URL вебхука Twilio корректен и публично доступен
  2. Убедитесь, что TWILIO_ACCOUNT_SID и TWILIO_AUTH_TOKEN верны
  3. Проверьте в Консоли Twilio → Monitor → Logs → Messaging на наличие ошибок доставки
  4. Убедитесь, что ваш номер телефона есть в SMS_ALLOWED_USERS (или установлен SMS_ALLOW_ALL_USERS=true)

Ответы не отправляются​

  1. Проверьте, что TWILIO_PHONE_NUMBER установлен корректно (формат E.164 с +)
  2. Убедитесь, что ваш аккаунт Twilio имеет номера с поддержкой SMS
  3. Проверьте логи шлюза VibeOS на наличие ошибок API Twilio

Конфликты портов вебхука​

Если порт 8080 уже занят, измените его:

SMS_WEBHOOK_PORT=3001

Обновите URL вебхука в Консоли Twilio соответствующим образом.