sidebar_position: 8 sidebar_label: "SMS (Twilio)" title: "SMS (Twilio)" description: "Set up Hermes Agent as an SMS chatbot via Twilio" lang: ru

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

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

ℹ️ Info

Общие учетные данные Шлюз SMS использует учетные данные совместно с необязательным [навыком телефонии](/docs/reference/skills-catalog). Если вы уже настроили Twilio для голосовых вызовов или одноразовых SMS, шлюз работает с теми же `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` и `TWILIO_PHONE_NUMBER`.

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

Учетная запись Twilio — Зарегистрируйтесь на twilio.com (доступна бесплатная пробная версия)
Номер телефона Twilio с возможностью отправки SMS.
Общедоступный сервер — Twilio отправляет веб-перехватчики на ваш сервер при поступлении SMS.
aiohttp — pip install 'hermes-agent[sms]'

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

Перейдите в Консоль Twilio
Скопируйте SID аккаунта и токен аутентификации с панели управления.
Перейдите в раздел Телефонные номера → Управление → Активные номера — запишите свой номер телефона в формате 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

# Security: restrict to specific phone numbers (recommended)
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Optional: set a home channel for cron job delivery
SMS_HOME_CHANNEL=+15559876543

Шаг 3. Настройте Twilio Webhook

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

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

💡 Tip

Exposing Your Webhook If you're running Hermes locally, use a tunnel to expose the webhook:

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

# Using ngrok
ngrok http 8080

Set the resulting public URL as your Twilio webhook.

Set SMS_WEBHOOK_URL to the same URL you configured in Twilio. This is required for Twilio signature validation — the adapter will refuse to start without it:

# Must match the webhook URL in your Twilio Console
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

The webhook port defaults to 8080. Override with:

SMS_WEBHOOK_PORT=3000

Step 4: Start the Gateway

hermes gateway

You should see:

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

If you see Отказ в запуске: SMS_WEBHOOK_URL требуется, set SMS_WEBHOOK_URL to the public URL configured in your Twilio Console (see Step 3).

Text your Twilio number — Hermes will respond via SMS.

Environment Variables

Variable	Required	Description
`TWILIO_ACCOUNT_SID`	Yes	Twilio Account SID (starts with `AC`)
`TWILIO_AUTH_TOKEN`	Yes	Twilio Auth Token (also used for webhook signature validation)
`TWILIO_PHONE_NUMBER`	Yes	Your Twilio phone number (E.164 format)
`SMS_WEBHOOK_URL@@IC0 016@@SMS_WEBHOOK_PORT`	No	Webhook listener port (default: `8080`)
`SMS_WEBHOOK_HOST`	No	Webhook bind address (default: `0.0.0.0@@ IC0020@@SMS_INSECURE_NO_SIGNATURE`
`SMS_ALLOWED_USERS@@IC00 23@@SMS_ALLOW_ALL_USERS`	No	Set to `true` to allow anyone (not recommended)
`SMS_HOME_CHANNEL`	No	Phone number for cron job / notification delivery
`SMS_HOME_CHANNEL_NAME`	No	Display name for the home channel (default: `Home`)

SMS-Specific Behavior

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

Security

Webhook signature validation

Hermes validates that inbound webhooks genuinely originate from Twilio by verifying the X-Twilio-Signature header (HMAC-SHA1). This prevents attackers from injecting forged messages.

SMS_WEBHOOK_U RL is required. Set it to the public URL configured in your Twilio Console. The adapter will refuse to start without it.

For local development without a public URL, you can disable validation:

# Local dev only — NOT for production
SMS_INSECURE_NO_SIGNATURE=true

User allowlists

The gateway denies all users by default. Configure an allowlist:

# Recommended: restrict to specific phone numbers
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Or allow all (NOT recommended for bots with terminal access)
SMS_ALLOW_ALL_USERS=true

⚠️ Warning

SMS has no built-in encryption. Don't use SMS for sensitive operations unless you understand the security implications. For sensitive use cases, prefer Signal or Telegram.

Troubleshooting

Messages not arriving

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)

Replies not sending

Check TWILIO_PHONE_NUMBER is set correctly (E.164 format with +)
Убедитесь, что в вашей учетной записи Twilio есть номера с поддержкой SMS.
Проверьте журналы шлюза Hermes на наличие ошибок Twilio API.

Конфликты портов Webhook

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

SMS_WEBHOOK_PORT=3001

Обновите URL-адрес веб-перехватчика в консоли Twilio, чтобы он соответствовал.