🏠 Главная › user guide › sms

Настройка СМС (Twilio)

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

ℹ️ Info

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

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

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

  1. Перейдите в Консоль Twilio
  2. Скопируйте SID аккаунта и Токен аутентификации с панели управления.
  3. Перейдите в Телефонные номера → Управление → Активные номера — запишите свой номер телефона в формате E.164 (например, +15551234567)

Шаг 2: Настраиваем Гермес

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

hermes gateway setup

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

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

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

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

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

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

Шаг 3: Настраиваем вебхук Twilio

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

  1. Перейдите в Номера телефонов → Управление → Активные номера.
  2. Нажмите на свой номер телефона.
  3. В разделе Сообщения → ПРИХОДИТ СООБЩЕНИЕ установите:
  4. Вебхук: https://ваш-сервер:8080/webhooks/twilio
  5. Метод HTTP: POST

    💡 Tip

    Открытие вашего вебхука Если вы запускаете Hermes локально, воспользуйтесь туннелем, чтобы открыть вебхук:
# Используя 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://your-server:8080/webhooks/twilio

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

SMS_WEBHOOK_PORT=3000

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

hermes gateway

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

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

Если вы видите «Отказ в запуске: требуется SMS_WEBHOOK_URL», установите «SMS_WEBHOOK_URL» в публичном URL-адресе, настроенном в консоли вашей Twilio (см. Шаг 3).

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

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

Переменная Обязательно Описание
TWILIO_ACCOUNT_SID Да 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 Нет Адрес привязки вебхука (по умолчанию: 0.0.0.0)
SMS_INSECURE_NO_SIGNATURE Нет Установите true, чтобы отключить проверку загрузки (только для локальной разработки — не для продакшена)
SMS_ALLOWED_USERS Нет Разделённые запятыми номера телефонов в формате E.164, которыми разрешено общение
SMS_ALLOW_ALL_USERS Нет Установите true, чтобы разрешить все (не рекомендуется)
SMS_HOME_CHANNEL Нет Номер телефона для решения задачи cron / протокол
SMS_HOME_CHANNEL_NAME Нет Отражаемое имя для канала домашнего (по умолчанию: Дом)

Поведение, специальное для SMS

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

Проверка вебхука

Гермес впоследствии обнаружил, что входящие вебхуки действительно исходят от 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.</div>
---

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

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

1. Убедитесь, что URL-адрес вебхука Twilio правильный и общедоступен.
2. Убедитесь, что `TWILIO_ACCOUNT_SID` и `TWILIO_AUTH_TOKEN` верны.
3. Проверить наличие консоли Twilio → **Монитор → Журналы → Сообщения** на ошибки доставки
4. Убедитесь, что ваш номер телефона есть в `SMS_ALLOWED_USERS` (или `SMS_ALLOW_ALL_USERS=true`)

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

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

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

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

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