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_USERSfilters senders. Caller ID is spoofable, making it a filter rather than authenticationPLIVO_SMS_INSECURE_NO_SIGNATUREweakens 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
1 maintainer
Metadata
1 maintainer
Release files for hermes-plivo-sms-gateway 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hermes_plivo_sms_gateway-0.1.0.tar.gz | 23.4 kB | With provenance | Details for hermes_plivo_sms_gateway-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hermes_plivo_sms_gateway-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for hermes_plivo_sms_gateway-0.1.0-py3-none-any.whl |
Total release size: 45.2 kB
Release files / hermes_plivo_sms_gateway-0.1.0.tar.gz
| Download URL | hermes_plivo_sms_gateway-0.1.0.tar.gz |
|---|---|
| Size | 23.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a9ef5b754cff08c26dbf091d77a3ed1eb14e9c220ebce859decf91c6e65453df
|
|
BLAKE2b-256 checksum How to use checksums |
5c06980cbd5529da39c75ab37744dfe55ceb84222fc4f66d2ef998a5a13f3f4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / hermes_plivo_sms_gateway-0.1.0-py3-none-any.whl
| Download URL | hermes_plivo_sms_gateway-0.1.0-py3-none-any.whl |
|---|---|
| Size | 21.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9fcd1f1fbb68de865bb579c4792289a26cc66d6637a0f393448744b059301871
|
|
BLAKE2b-256 checksum How to use checksums |
586dae16deb5e2a38e1b0e22bed8fba430b82cb7bd698ce82cd2d6922ef69f00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logSecurity for hermes-plivo-sms-gateway 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for hermes_plivo_sms_gateway-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
