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.

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 callers. Caller ID is spoofable, making it a filter rather than authentication
• 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