hermes-plivo-sms-gateway

Plivo SMS channel for Hermes Agent. A text sent to a Plivo number reaches the agent as a conversation turn, and the reply arrives back over Plivo as an SMS.

Capability Detail
Two-way SMS Any Hermes agent becomes reachable by text
Sessions Each sender number holds its own independent conversation
Formatting Markdown becomes plain text, and a long reply splits across segments
Scheduled delivery Cron and notification messages reach a home number without a live session
Provisioning Plivo is configured automatically on every start, including a public URL

Hermes provides the model turn. The plugin handles messaging transport, webhook security and the Plivo-side configuration.

Requirements
Hermes Agent With the gateway. Python 3.11 or later
Plivo An account and an SMS-capable number

cloudflared is fetched automatically when no public URL is configured.

Installation

1. Install

pip install hermes-plivo-sms-gateway

2. Enable

hermes plugins enable plivo_sms-platform
hermes plugins list

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

3. Add credentials

In ~/.hermes/.env:

PLIVO_AUTH_ID=MAxxxxxxxxxxxxxxxxxx
PLIVO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
PLIVO_PHONE_NUMBER=+14155550100

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

Texting the number reaches the agent once the gateway is up. A temporary tunnel can take up to 2 minutes. Setting PLIVO_SMS_PUBLIC_URL removes the delay.

Configuration

Read from ~/.hermes/.env.

Required

Variable Purpose
PLIVO_AUTH_ID Plivo auth ID
PLIVO_AUTH_TOKEN Plivo auth token. Also verifies inbound webhook signatures
PLIVO_PHONE_NUMBER The SMS-capable number the agent texts from, E.164

Optional

Variable Default Purpose
PLIVO_SMS_PUBLIC_URL unset Public HTTPS base Plivo reaches the webhook on. Required for deployment. A temporary tunnel is opened when unset, and its URL rotates per run
PLIVO_SMS_ALLOWED_USERS empty Comma-separated sender numbers, digits only
PLIVO_SMS_ALLOW_ALL_USERS false true admits every sender
PLIVO_SMS_HOME_CHANNEL unset Number receiving cron and notification messages
PLIVO_SMS_AUTO_WIRE true false leaves the Plivo application and number untouched, to be configured by hand
PLIVO_SMS_WEBHOOK_PORT 8090 Local port for the webhook server
PLIVO_SMS_WEBHOOK_HOST 127.0.0.1 Local bind address for the webhook server
PLIVO_SMS_INSECURE_NO_SIGNATURE false true accepts unverified webhooks. Development only

Security

  • Inbound webhooks are verified against Plivo's MA-V3 signature, using the account auth token
  • Plivo applications and numbers the plugin did not create are never modified
  • PLIVO_SMS_ALLOWED_USERS filters senders. Caller ID is spoofable, making it a filter rather than authentication
  • PLIVO_SMS_INSECURE_NO_SIGNATURE weakens the above and belongs in development only

Troubleshooting

Symptom Cause
Plugin 'plivo_sms' is not installed or bundled The enable name needs the -platform suffix
No Plivo settings in hermes config Expected for a pip-installed plugin. Edit ~/.hermes/.env
Texts arrive, the agent never replies A sender number in PLIVO_SMS_ALLOWED_USERS written with a leading +
Webhook rejects every message The auth token in ~/.hermes/.env differs from the account signing the webhook
Replies arrive truncated A long reply splits across segments, and carriers may reorder them

Uninstalling

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

python -m hermes_plivo_sms.unwire
pip uninstall hermes-plivo-sms-gateway

The command only touches the application this plugin created, so a number wired to something else is left alone. It exits non-zero when it could not undo the configuration, which is what stops a runbook uninstalling over a live number.

Tests

python -m unittest discover -s tests
ruff check .

The suite covers the signature vectors, payload parsing, request validation and the pure configuration helpers. It needs no Hermes install and touches no network.

Limitations

  • One Plivo number answers through one application, leaving the SMS and voice plugins unable to share a number
  • Uninstalling leaves the Plivo application and number wired to a gateway no longer running

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Plivo from gravatar.com Plivo

Credits

Author: Plivo

License

MIT

Requires

Python >=3.11

Tags

hermes hermes-agent plivo sms gateway plugin

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hermes_plivo_sms_gateway-0.1.0.tar.gz (23.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hermes_plivo_sms_gateway-0.1.0-py3-none-any.whl (21.8 kB view details)

Uploaded Python 3

File details

Details for the file hermes_plivo_sms_gateway-0.1.0.tar.gz.

File metadata

  • Download URL: hermes_plivo_sms_gateway-0.1.0.tar.gz
  • Upload date:
  • Size: 23.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hermes_plivo_sms_gateway-0.1.0.tar.gz
Algorithm Hash digest
SHA256 a9ef5b754cff08c26dbf091d77a3ed1eb14e9c220ebce859decf91c6e65453df
MD5 c6fc0879a0f05fccfffa5b1ac56491ad
BLAKE2b-256 5c06980cbd5529da39c75ab37744dfe55ceb84222fc4f66d2ef998a5a13f3f4a

See more details on using hashes here.

Provenance

The following attestation bundles were made for hermes_plivo_sms_gateway-0.1.0.tar.gz:

Publisher: publish.yml on plivo-dev/hermes-plivo-sms-gateway

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hermes_plivo_sms_gateway-0.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for hermes_plivo_sms_gateway-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9fcd1f1fbb68de865bb579c4792289a26cc66d6637a0f393448744b059301871
MD5 d94563482f1d661a502e637dfdceaec4
BLAKE2b-256 586dae16deb5e2a38e1b0e22bed8fba430b82cb7bd698ce82cd2d6922ef69f00

See more details on using hashes here.

Provenance

The following attestation bundles were made for hermes_plivo_sms_gateway-0.1.0-py3-none-any.whl:

Publisher: publish.yml on plivo-dev/hermes-plivo-sms-gateway

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page