Telnyx Hermes Sms

Telnyx Hermes SMS

Use Telnyx Messaging as a first-class Hermes platform adapter.

Install into Hermes

mkdir -p ~/.hermes/plugins/telnyx_sms
cp __init__.py adapter.py plugin.yaml ~/.hermes/plugins/telnyx_sms/
hermes plugins list
hermes plugins enable telnyx-sms-platform  # or telnyx_sms depending on CLI key

Restart the Hermes gateway after enabling the plugin.

Configuration

Required:

export TELNYX_API_KEY="KEY..."
export TELNYX_SMS_FROM_NUMBER="+15551234567"

Recommended production hardening:

export TELNYX_PUBLIC_KEY="<Telnyx webhook signing public key>"
export TELNYX_SMS_REQUIRE_SIGNATURE=true
export TELNYX_SMS_ALLOWED_USERS="+15551230001,+15551230002"

Optional:

export TELNYX_MESSAGING_PROFILE_ID="400..."
export TELNYX_SMS_API_BASE="https://api.telnyx.com/v2"
export TELNYX_SMS_WEBHOOK_HOST="0.0.0.0"
export TELNYX_SMS_WEBHOOK_PORT=8087
export TELNYX_SMS_WEBHOOK_PATH="/webhooks/telnyx/sms"
export TELNYX_SMS_HOME_CHANNEL="+15551230001"
export TELNYX_SMS_SIGNATURE_TOLERANCE=300

Hermes config

gateway:
  platforms:
    telnyx_sms:
      enabled: true

Or rely on env-driven enablement when TELNYX_API_KEY and TELNYX_SMS_FROM_NUMBER are set and the plugin is enabled.

Webhook

Configure the Telnyx Messaging Profile inbound webhook to:

https://your-public-host.example/webhooks/telnyx/sms

The adapter accepts inbound message.received webhooks and ignores delivery receipt lifecycle events.

Tests

uv run --extra test python -m pytest tests/test_telnyx_sms_static.py tests/test_telnyx_sms_runtime.py -q

Live SMS send test requires an explicit safety flag and sends a real SMS:

export TELNYX_API_KEY="KEY..."
export TELNYX_SMS_FROM_NUMBER="+15551234567"
export TELNYX_SMS_TEST_TO="+15557654321"
export TELNYX_SMS_LIVE_TEST=1
uv run --extra test python -m pytest tests/test_telnyx_sms_live.py -q -m live