helliomessaging 1.0.0

Official Python SDK for the Hellio Messaging API (SMS, OTP, Voice, Number Lookup, Email Verification, Webhooks).

Hellio Messaging - Official Python SDK

Python client for the Hellio Messaging API v1: SMS, OTP (SMS / email / voice), Voice broadcasts, Number Lookup (HLR), Email Verification, and Webhooks. Fully type-hinted and synchronous.

Install

pip install helliomessaging

The import package is hellio (the main class is Hellio).

Configure

Generate a token in your dashboard -> Settings -> API -> Generate API token, then construct the client directly:

from hellio import Hellio

client = Hellio(
    token="your-token-here",
    default_sender="HellioSMS",   # optional default Sender ID for SMS
)

Or rely on environment variables:

HELLIO_API_TOKEN=your-token-here
HELLIO_BASE_URL=https://api.helliomessaging.com/v1
HELLIO_DEFAULT_SENDER=HellioSMS

client = Hellio()   # reads HELLIO_API_TOKEN, HELLIO_BASE_URL, HELLIO_DEFAULT_SENDER

Every call returns the decoded JSON response as a dict (payloads are under the data key). You can also use the client as a context manager so the underlying HTTP connection is closed for you:

with Hellio(token="your-token-here") as client:
    client.balance()

Usage

from hellio import Hellio

client = Hellio(token="your-token-here", default_sender="HellioSMS")

# Account
client.balance()            # {'data': {'balance': '195.0000', 'available': '194.65', ...}}
client.pricing("GH")        # optional ISO-2 country filter
client.pricing()            # all networks

# SMS (recipients: string, comma list, or list)
client.sms("233241234567", "Hello!")
client.sms(["233241234567", "233201234567"], "Hi all", sender="HellioSMS")
client.message(1024)        # delivery status
client.campaign(1024)       # campaign summary

# OTP - sender (Sender ID) is REQUIRED for sms/voice and must be approved on your account.
# Optional length (4-10 digits) and expiry (minutes). Returns status "queued".
client.otp("233241234567", "HellioSMS")                          # SMS
client.otp("233241234567", "HellioSMS", channel="voice")         # Voice (TTS reads the code)
client.otp("233241234567", "HellioSMS", length=6, expiry=10)     # custom length / expiry
client.otp("[e-mail]", channel="email")                  # Email (no sender)
client.verify("233241234567", "123456")                          # bool
client.verify_otp("[e-mail]", "123456", channel="email") # full response

# Voice broadcast - text (we TTS it) or a hosted audio_url
client.voice("233241234567", "HELLIO", text="Your code is 1 2 3 4")
client.voice(["233241234567"], "HELLIO", audio_url="https://cdn.example.com/promo.mp3")
client.voice_status(42)

# Number lookup (HLR) - async; poll results
client.lookup(["233241234567"])
client.lookups()
client.lookup_result(5)

# Email verification
client.verify_email(["[e-mail]", "[e-mail]"])

# Webhooks (receive delivery reports)
client.create_webhook("https://your-app.com/hooks/hellio", ["message.delivered", "message.failed"])
client.webhooks()
client.delete_webhook(1)

Error handling

Non-2xx responses raise typed exceptions (all extend HellioError). Each error carries message, status_code, and response (the parsed body); validation errors also expose errors.

Exception	Status
InvalidApiTokenError	401
InsufficientBalanceError	402
ValidationError (.errors)	422
RateLimitError	429
HellioError	other

from hellio import Hellio, InsufficientBalanceError

client = Hellio(token="your-token-here")

try:
    client.sms("233241234567", "Hi")
except InsufficientBalanceError:
    ...  # top up

verify() is a convenience wrapper: it returns False on a 422 validation error (invalid code) instead of raising.

Rate limit: 120 requests/minute per token.

Testing against the SDK

The client accepts an injected httpx.Client, so you can mock the transport in your own tests (for example with respx):

import httpx
from hellio import Hellio

client = Hellio(token="test", http_client=httpx.Client(base_url="https://api.helliomessaging.com/v1/"))

License

MIT