{/ This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. /}

Telephony

Give Hermes phone capabilities without core tool changes. Provision and persist a Twilio number, send and receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi.

Skill metadata


Source	Optional — install with `hermes skills install official/productivity/telephony`
Path	`optional-skills/productivity/telephony`
Version	`1.0.0`
Author	Nous Research
License	MIT
Platforms	linux, macos, windows
Tags	`telephony`, `phone`, `sms`, `mms`, `voice`, `twilio`, `bland.ai`, `vapi`, `calling`, `texting`
Related skills	`maps`, `google-workspace`, `agentmail`

Reference: full SKILL.md
ℹ️ Info

The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

Telephony — Numbers, Calls, and Texts without Core Tool Changes

This optional skill gives Hermes practical phone capabilities while keeping telephony out of the core tool list.

It ships with a helper script, scripts/telephony.py, that can: - save provider credentials into ~/.hermes/.env - search for and buy a Twilio phone number - remember that owned number for later sessions - send SMS / MMS from the owned number - poll inbound SMS for that number with no webhook server required - make direct Twilio calls using TwiML <Say> or <Play> - import the owned Twilio number into Vapi - place outbound AI calls through Bland.ai or Vapi

What this solves

This skill is meant to cover the practical phone tasks users actually want: - outbound calls - texting - owning a reusable agent number - checking messages that arrive to that number later - preserving that number and related IDs between sessions - future-friendly telephony identity for inbound SMS polling and other automations

It does not turn Hermes into a real-time inbound phone gateway. Inbound SMS is handled by polling the Twilio REST API. That is enough for many workflows, including notifications and some one-time-code retrieval, without adding core webhook infrastructure.

Safety rules — mandatory

Always confirm before placing a call or sending a text.
Never dial emergency numbers.
Never use telephony for harassment, spam, impersonation, or anything illegal.
Treat third-party phone numbers as sensitive operational data:
do not save them to Hermes memory
do not include them in skill docs, summaries, or follow-up notes unless the user explicitly wants that
It is fine to persist the agent-owned Twilio number because that is part of the user's configuration.
VoIP numbers are not guaranteed to work for all third-party 2FA flows. Use with caution and set user expectations clearly.

Decision tree — which service to use?

Use this logic instead of hardcoded provider routing:

1) "I want Hermes to own a real phone number"

Use Twilio.

Why: - easiest path to buying and keeping a number - best SMS / MMS support - simplest inbound SMS polling story - cleanest future path to inbound webhooks or call handling

Use cases: - receive texts later - send deployment alerts / cron notifications - maintain a reusable phone identity for the agent - experiment with phone-based auth flows later

2) "I only need the easiest outbound AI phone call right now"

Use Bland.ai.

Why: - quickest setup - one API key - no need to first buy/import a number yourself

Tradeoff: - less flexible - voice quality is decent, but not the best

3) "I want the best conversational AI voice quality"

Use Twilio + Vapi.

Why: - Twilio gives you the owned number - Vapi gives you better conversational AI call quality and more voice/model flexibility

Recommended flow: 1. Buy/save a Twilio number 2. Import it into Vapi 3. Save the returned VAPI_PHONE_NUMBER_ID 4. Use ai-call --provider vapi

4) "I want to call with a custom prerecorded voice message"

Use Twilio direct call with a public audio URL.

Why: - easiest way to play a custom MP3 - pairs well with Hermes text_to_speech plus a public file host or tunnel

Files and persistent state

The skill persists telephony state in two places:

`~/.hermes/.env`

Used for long-lived provider credentials and owned-number IDs, for example: - 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 call provider: bland or vapi)

`~/.hermes/telephony_state.json`

Used for skill-only state that should survive across sessions, for example: - remembered default Twilio number / SID - remembered Vapi phone number ID - last inbound message SID/date for inbox polling checkpoints

This means: - the next time the skill is loaded, diagnose can tell you what number is already configured - twilio-inbox --since-last --mark-seen can continue from the previous checkpoint

Locate the helper script

After installing this skill, locate the script like this:

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

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

Установить

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

hermes skills search telephony
hermes skills install official/productivity/telephony

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

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

Зарегистрируйтесь по адресу: - https://www.twilio.com/try-twilio

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

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
# or
python3 "$SCRIPT" twilio-set-default PNXXXXXXXXXXXXXXXXXXXXXXXXXXXX --save-env

Bland.ai — самые простые исходящие вызовы с помощью ИИ

Зарегистрируйтесь по адресу: - https://app.bland.ai

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

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

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

Зарегистрируйтесь по адресу: - https://dashboard.vapi.ai

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

python3 "$SCRIPT" save-vapi your_vapi_api_key

Импортируйте свой номер Twilio в Vapi и сохраните возвращенный идентификатор номера телефона:

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

Если вы уже знаете идентификатор номера телефона Vapi, сохраните его:

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

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

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

python3 "$SCRIPT" diagnose

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

Общие рабочие процессы

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

Сохраните учетные данные Twilio:

python3 "$SCRIPT" save-twilio AC... auth_token_here

Найдите номер:

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

Купите его и сохраните в ~/.hermes/.env + состояние:

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

В следующем сеансе запустите:

python3 "$SCRIPT" diagnose

Здесь отображается запомненный номер по умолчанию и состояние контрольной точки папки «Входящие».

Б. Отправьте СМС с номера агента

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 Hermes calling with your status update." --voice Polly.Joanna

E. Звонок с помощью заранее записанного/собственного голосового сообщения

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

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

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

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

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

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

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

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

Важное примечание: - Hermes TTS отлично подходит для предварительно записанных исходящих сообщений. - Bland/Vapi лучше подходят для разговорных вызовов AI в реальном времени, поскольку они сами обрабатывают аудиостек телефонной связи в реальном времени. - Hermes 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

После завершения задайте вопросы по анализу Бланда:

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

H. Исходящий телефонный звонок через AI с Vapi на ваш номер

Импортируйте свой номер Twilio в Vapi:

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

Сделайте звонок:

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

Проверьте результат:

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

Чего еще не делает этот навык

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

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

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

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

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

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

«Диагностика» показывает готовность провайдера и запомненное состояние.
найти и купить номер Twilio
сохраните это число в ~/.hermes/.env
отправить СМС со своего номера
позже опросить входящие тексты на наличие принадлежащего номера
совершить прямой вызов Twilio
сделать AI-вызов через Bland или Vapi.

Ссылки

Номера телефонов Twilio: https://www.twilio.com/docs/phone-numbers/api.
Обмен сообщениями Twilio: https://www.twilio.com/docs/messaging/api/message-resource.
Голос Twilio: https://www.twilio.com/docs/voice/api/call-resource
Документы Вапи: https://docs.vapi.ai/
Бланд.ай: https://app.bland.ai/