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

Hermes connects to SMS through the Twilio API. People text your Twilio phone number and get AI responses back — same conversational experience as Telegram or Discord, but over standard text messages.

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

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

Twilio account — Sign up at twilio.com (free trial available)
A Twilio phone number with SMS capability
A publicly accessible server — Twilio sends webhooks to your server when SMS arrives
aiohttp — pip install 'hermes-agent[sms]'

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

Go to the Twilio Console
Copy your Account SID and Auth Token from the dashboard
Go to Phone Numbers → Manage → Active Numbers — note your phone number in E.164 format (e.g., +15551234567)

Шаг 2: Настройка Hermes

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

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 должен знать, куда отправлять входящие сообщения. В консоли Twilio:

Go to Phone Numbers → Manage → Active Numbers
Click your phone number
Under Messaging → A MESSAGE COMES IN, set:
Webhook: https://your-server:8080/webhooks/twilio
HTTP-метод: POST

tip Exposing Your Webhook Если Hermes работает локально, используйте туннель для публикации вебхука:

# Using cloudflared
cloudflared tunnel --url http://localhost:8080

# Using 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

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

Отправьте SMS на ваш номер Twilio — Hermes ответит через SMS.

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

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

Особенности поведения SMS

Plain text only — Markdown is automatically stripped since SMS renders it as literal characters
1600 character limit — Longer responses are split across multiple messages at natural boundaries (newlines, then spaces)
Echo prevention — Messages from your own Twilio number are ignored to prevent loops
Phone number redaction — Phone numbers are redacted in logs for privacy

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

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

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

Диагностика проблем

Сообщения не поступают

Check your Twilio webhook URL is correct and publicly accessible
Verify TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN are correct
Check the Twilio Console → Monitor → Logs → Messaging for delivery errors
Ensure your phone number is in SMS_ALLOWED_USERS (or SMS_ALLOW_ALL_USERS=true)

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

Check TWILIO_PHONE_NUMBER is set correctly (E.164 format with +)
Verify your Twilio account has SMS-capable numbers
Check Hermes gateway logs for Twilio API errors

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

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

SMS_WEBHOOK_PORT=3001

Обновите URL вебхука в консоли Twilio соответственно.