hermes-plivo-phone-gateway

Plivo voice channel for Hermes Agent. Real-time phone conversations with the agent over Plivo, inbound and outbound.

Speech-to-text, the model turn and text-to-speech are Hermes settings, shared with every other channel. The plugin handles telephony and barge-in.

Requirements

cloudflared is fetched automatically when no public URL is configured.

Installation

1. Install

pip install hermes-plivo-phone-gateway

hermes-plivo-tools is installed alongside it and provides outbound calling.

2. Enable

hermes plugins enable plivo_voice-platform
hermes plugins list

The name includes the -platform suffix. Hermes strips it to derive the channel name plivo_voice, and rejects the short form.

3. Add credentials

In ~/.hermes/.env:

PLIVO_AUTH_ID=MAxxxxxxxxxxxxxxxxxx
PLIVO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
PLIVO_PHONE_NUMBER=+14155550100

hermes gateway setup lists these three. Additional optional settings live in the same file and are listed under Configuration. A pip-installed plugin does not appear in the hermes config screens.

4. Start the gateway

hermes gateway run          # foreground
hermes gateway install      # or as a supervised service

The number can be reached once the log reads:

[plivo_voice] READY. Call +141****0100 to talk to the agent.

A temporary tunnel can take up to 2 minutes. Setting PLIVO_VOICE_PUBLIC_URL removes the delay. Numbers are masked in Hermes logs.

5. Verify

python -m hermes_plivo_voice.doctor

Checks credentials, the Plivo API, the registered answer URL, text-to-speech, speech detection and the caller allowlist, and reports which of them would stop a call working.

Outbound calls

hermes-plivo-tools is installed as a dependency and only needs enabling:

hermes plugins enable plivo-tools

Enabling adds make_call, send_sms and lookup_number. The plugin answers the outbound call itself, and whoever picks up talks to the agent exactly as an inbound caller would.

Call +14155550100 and ask what time the meeting starts.

A call is refused rather than placed when the plugin's answer URL is not responding, or when Plivo rejects the credentials.

Configuration

Read from ~/.hermes/.env. Speech providers are configured in ~/.hermes/config.yaml under stt and tts, documented in Hermes' voice mode guide.

Required

Optional

Audio rates, speech-detection thresholds and interruption sensitivity are not configurable.

Tool scope

platform_toolsets in ~/.hermes/config.yaml limits the toolsets a caller can reach. The key is plivo_voice, the plugin name without the -platform suffix.

platform_toolsets:
  plivo_voice:
    - plivo_send_sms
    - plivo_make_call
    - plivo_lookup_number
    - web
    - memory

Without an entry a caller reaches every toolset except the ones Hermes ships switched off and anything under agent.disabled_toolsets. A plugin's toolsets are enabled by default, so the Plivo tools are reachable either way. Saving a toolset list for a platform through hermes tools reverses that for plugin toolsets, because from then on one absent from the saved list counts as switched off. The startup log names the toolsets a caller can reach.

Exclude any tool the agent can call but cannot complete. It calls the tool regardless, and the failure and retry are dead air on the line.

Security

• Answer callbacks are signature-verified against every signature header Plivo sends
• Each call mints a short-lived token carried in the audio WebSocket URL
• Plivo applications and numbers the plugin did not create are never modified
• PLIVO_VOICE_ALLOWED_USERS filters who may call the agent, and PLIVO_VOICE_ALLOWED_DESTINATIONS filters who the agent may call. The two lists are independent, so a number in one is not permitted by the other
• An empty inbound list admits every caller, while an empty outbound list refuses every call. Outbound spends money and rings a stranger, where an unexpected inbound call only spends tokens
• The caller's number is not verified, so anyone who knows an allowed number can dial in as that number
• PLIVO_VOICE_INSECURE_NO_SIGNATURE and PLIVO_VOICE_RAW_DUMP both weaken the above

Troubleshooting

Run python -m hermes_plivo_voice.doctor first.

Uninstalling

Plivo keeps sending calls to a number until it is detached. Undo the Plivo side before removing the plugin:

python -m hermes_plivo_voice.unwire
pip uninstall hermes-plivo-phone-gateway

Tests

python -m unittest discover -s tests
ruff check .

tests/ also holds scripts driving a synthetic call through a live gateway. See tests/README.md.

Limitations

• One Plivo number answers through one application, leaving the voice and SMS plugins unable to share a number
• Reply length is requested in the per-turn prompt, not enforced
• Speech providers are global Hermes settings, and changing one affects every channel

License

MIT