Skip to main content

Telephony

赋予 Hermes 电话能力，无需修改核心工具。配置并永久持有 Twilio 号码，发送和接收 SMS/MMS，直接拨打电话，以及通过 Bland.ai 或 Vapi 进行 AI 驱动的外呼。

技能元数据​

来源可选 — 使用 hermes skills install official/productivity/telephony 安装
路径optional-skills/productivity/telephony
版本1.0.0
作者Nous Research
许可证MIT
平台linux, macos, windows
标签telephony, phone, sms, mms, voice, twilio, bland.ai, vapi, calling, texting
相关技能maps, google-workspace, agentmail

参考：完整 SKILL.md​

info

以下是 Hermes 在触发此技能时加载的完整技能定义。这是 Agent 在技能激活时看到的指令。

Telephony — 无需修改核心工具即可管理号码、通话和短信

这个可选技能赋予 Hermes 实用的电话能力，同时将电话功能排除在核心工具列表之外。

它附带一个辅助脚本 scripts/telephony.py，可以：

  • 将提供商凭证保存到 ~/.hermes/.env
  • 搜索并购买 Twilio 电话号码
  • 记住所拥有的号码以便后续会话使用
  • 从所拥有的号码发送 SMS/MMS
  • 轮询该号码的入站短信（无需 webhook 服务器）
  • 使用 TwiML <Say> 或 <Play> 直接发起 Twilio 通话
  • 将所拥有的 Twilio 号码导入 Vapi
  • 通过 Bland.ai 或 Vapi 进行 AI 驱动外呼

解决的问题​

此技能旨在满足用户实际需要的电话操作任务：

  • 外呼
  • 发短信
  • 拥有一个可重复使用的 Agent 号码
  • 检查稍后到达该号码的消息
  • 在会话之间保留该号码及相关 ID
  • 为入站短信轮询和其他自动化任务提供面向未来的电话标识

它不会将 Hermes 变成一个实时入站电话网关。入站短信通过轮询 Twilio REST API 处理。这对许多工作流来说已经足够，包括通知和某些一次性代码获取，而无需添加核心 webhook 基础设施。

安全规则 — 必须遵守​

  1. 在拨打电话或发送短信之前，务必确认。
  2. 切勿拨打紧急号码。
  3. 切勿将电话功能用于骚扰、垃圾信息、冒名顶替或任何非法行为。
  4. 将第三方电话号码视为敏感操作数据：
    • 不要将它们保存到 Hermes 记忆体中
    • 除非用户明确要求，否则不要将它们包含在技能文档、摘要或后续笔记中
  5. 可以持久化 Agent 拥有的 Twilio 号码，因为它是用户配置的一部分。
  6. VoIP 号码不保证 适用于所有第三方双重认证流程。请谨慎使用，并明确告知用户预期。

决策树 — 应该用哪个服务？​

用下面这个逻辑来代替硬编码的提供商路由：

1）“我想让 Hermes 拥有一个真实的电话号码”​

使用 Twilio。

原因：

  • 购买和保留号码的最简单途径
  • 最好的 SMS / MMS 支持
  • 最简单的入站 SMS 轮询方案
  • 未来处理入站 webhook 或电话呼叫的最清晰路径

使用场景：

  • 之后接收短信
  • 发送部署告警 / cron 通知
  • 为 Agent 维护一个可复用的电话号码身份
  • 之后尝试基于电话的认证流程

2）“我现在只需要最简单的出站 AI 电话”​

使用 Bland.ai。

原因：

  • 搭建最快
  • 一个 API key 即可
  • 无需先自己购买/导入号码

权衡：

  • 灵活性较低
  • 语音质量尚可，但不是最好

3）“我想要最好的对话式 AI 语音质量”​

使用 Twilio + Vapi。

原因：

  • Twilio 提供你拥有的号码
  • Vapi 提供更好的对话式 AI 通话质量和更多的语音/模型灵活性

推荐流程：

  1. 购买/保存一个 Twilio 号码
  2. 将其导入 Vapi
  3. 保存返回的 VAPI_PHONE_NUMBER_ID
  4. 使用 ai-call --provider vapi

4）“我想用自定义预录语音消息打电话”​

使用带有公共音频 URL 的 Twilio 直拨电话。

原因：

  • 播放自定义 MP3 的最简单方式
  • 配合 Hermes 的 text_to_speech 以及公共文件托管或隧道效果很好

文件和持久状态​

该 Skill 在两个位置持久化电话状态：

~/.hermes/.env​

用于长期有效的提供商凭证和拥有的号码 ID，例如：

  • 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 通话提供商：bland 或 vapi）

~/.hermes/telephony_state.json​

用于只属于该 Skill 且应在会话间持久化的状态，例如：

  • 记住的默认 Twilio 号码 / SID
  • 记住的 Vapi 电话号码 ID
  • 上次入站消息的 SID/日期（用于收件箱轮询检查点）

这意味着：

  • 下次加载该 Skill 时，diagnose 可以告诉你已配置的号码
  • twilio-inbox --since-last --mark-seen 可以从上一个检查点继续

找到辅助脚本​

安装此 Skill 后，这样定位脚本：

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

如果 SCRIPT 为空，说明该 Skill 尚未安装。

安装​

这是一个官方可选 Skill，所以请从 Skill 中心安装：

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

提供商设置​

Twilio — 拥有的号码、SMS/MMS、直拨电话、入站 SMS 轮询​

注册地址：

然后将凭据保存到 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
# 或
python3 "$SCRIPT" twilio-set-default PNXXXXXXXXXXXXXXXXXXXXXXXXXXXX --save-env

Bland.ai — 最简单的 AI 外呼方案​

注册地址：

保存配置：

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

Vapi — 更优质的对话语音质量​

注册地址：

先保存 API 密钥：

python3 "$SCRIPT" save-vapi your_vapi_api_key

将你拥有的 Twilio 号码导入 Vapi，并保存返回的电话号码 ID：

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

如果你已经知道 Vapi 的电话号码 ID，可以直接保存：

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

诊断当前状态​

随时查看该技能已知的信息：

python3 "$SCRIPT" diagnose

在后续会话中恢复工作时，请先执行此命令。

常见工作流​

A. 购买一个 Agent 号码并稍后继续使用​

  1. 保存 Twilio 凭据：
python3 "$SCRIPT" save-twilio AC... auth_token_here
  1. 搜索号码：
python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 10
  1. 购买号码并将其保存到 ~/.hermes/.env 和状态中：
python3 "$SCRIPT" twilio-buy "+17025551234" --save-env
  1. 下次会话时运行：
python3 "$SCRIPT" diagnose

这会显示已记住的默认号码和收件箱检查点状态。

B. 从 Agent 号码发送短信​

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. 稍后无需 Webhook 服务器即可检查收到的短信​

轮询默认 Twilio 号码的收件箱：

python3 "$SCRIPT" twilio-inbox --limit 20

仅显示上次检查点之后到达的消息，并在阅读完毕后将检查点前移：

python3 "$SCRIPT" twilio-inbox --since-last --mark-seen

这是“下次加载技能时如何访问该号码收到的消息？”的主要答案。

D. 使用内置 TTS 发起直接 Twilio 通话​

python3 "$SCRIPT" twilio-call "+15551230000" --message "Hello! This is Hermes calling with your status update." --voice Polly.Joanna

E. 使用预录 / 自定义语音消息进行通话​

这是复用 Hermes 现有 text_to_speech 支持的主要路径。

适用场景：

  • 希望通话使用 Hermes 配置的 TTS 语音，而非 Twilio <Say>
  • 需要单向语音传递（简报、提醒、笑话、通知、状态更新）
  • 不需要 实时的对话式电话通话

单独生成或托管音频，然后：

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

推荐的 Hermes TTS -> Twilio Play 工作流程：

  1. 使用 Hermes text_to_speech 生成音频。
  2. 将生成的 MP3 文件公开可访问。
  3. 使用 --audio-url 发起 Twilio 电话呼叫。

示例 Agent 流程：

  • 要求 Hermes 使用 text_to_speech 创建消息音频
  • 如有需要，通过临时静态主机/隧道/对象存储 URL 暴露文件
  • 使用 twilio-call --audio-url ... 通过电话发送

MP3 的良好托管选项：

  • 临时的公共对象/存储 URL
  • 指向本地静态文件服务器的短期隧道
  • 电话运营商可以直接获取的任何现有 HTTPS URL

重要说明：

  • Hermes TTS 适合预录的外呼消息
  • Bland/Vapi 更适合实时对话式 AI 通话，因为它们自己处理实时电话音频栈
  • 此处的 Hermes STT/TTS 并未用作全双工电话会话引擎；要实现全双工通话，需要比本技能介绍的更复杂的流式/webhook 集成

F. 通过 Twilio 直接拨号导航电话树/IVR​

如果在通话接通后需要按键，请使用 --send-digits。 Twilio 将 w 解释为短暂等待。

python3 "$SCRIPT" twilio-call "+18005551234" --message "正在为您转接账单部门。" --send-digits "ww1w2w3"

这在转接给人工或发送简短状态消息之前，需要到达特定菜单分支时非常有用。

G. 使用 Bland.ai 进行外呼 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

通话结束后询问 Bland 分析问题：

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

H. 使用您名下的号码通过 Vapi 进行外呼 AI 电话​

  1. 将您的 Twilio 号码导入 Vapi：
python3 "$SCRIPT" vapi-import-twilio --save-env
  1. 拨打电话：
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
  1. 检查结果：
python3 "$SCRIPT" ai-status <call_id> --provider vapi

建议的 Agent 流程​

当用户请求拨打电话或发送短信时：

  1. 通过决策树确定适合的路径。
  2. 如果配置状态不清晰，运行 diagnose。
  3. 收集完整的任务细节。
  4. 在拨号或发送短信前与用户确认。
  5. 使用正确的命令。
  6. 如有需要，轮询结果。
  7. 总结结果，不要将第三方号码持久化到 Hermes 记忆中。

该技能仍不支持的功能​

  • 实时接听来电
  • 基于 webhook 的实时短信推送至 Agent 循环
  • 保证支持任意第三方 2FA 提供商

这些功能需要的底层基础设施远超一个纯可选技能。

陷阱​

  • Twilio 试用账户和地区规则可能会限制你能呼叫或发送短信的对象。
  • 某些服务会拒绝 VoIP 号码用于 2FA。
  • twilio-inbox 轮询 REST API，并非即时推送。
  • Vapi 外呼仍然依赖于一个有效的已导入号码。
  • Bland 最简单，但音质不一定最好。
  • 不要将任意第三方电话号码存储在 Hermes 记忆体中。

验证清单​

设置完成后，你应该能够仅凭此技能完成以下所有操作：

  1. diagnose 显示提供者就绪状态和已记忆的状态
  2. 搜索并购买一个 Twilio 号码
  3. 将该号码持久化到 ~/.hermes/.env
  4. 从拥有的号码发送一条短信
  5. 稍后轮询该号码的入站短信
  6. 通过 Twilio 直接拨打电话
  7. 通过 Bland 或 Vapi 发起 AI 通话

参考链接​