irnoti (Python)

Python SDK for the irnoti API, built on httpx.

pip install irnoti

from irnoti import Irnoti, IrnotiApiError, parse_webhook

irnoti = Irnoti(api_key="irn_live_…")  # base_url, timeout, retries, http_client are optional

try:
    line = irnoti.lines.list()[0]["id"]
    irnoti.sms.quote(line, "Hi", to="09121234567")
    irnoti.sms.send(line, "Hi", to=["09121234567"], group_ids=[12], idempotency_key="k1")
    irnoti.sms.pattern("k3f9a2", "09121234567", {"code": "4821"})
    irnoti.services.create("regional", {"province": "tehran", "count": 5000, "text": "Sale"})
except IrnotiApiError as e:
    if e.is_insufficient_balance:
        ...  # top up
    else:
        raise

# Flask: verify against the raw body
event = parse_webhook(request.get_data(), request.headers["X-Irnoti-Signature"], WEBHOOK_SECRET)

Multi-tenant: irnoti.with_api_key(customer_key) returns an independent client. Optional request fields use the API's camelCase names where they are passed as **options / dicts (e.g. verify.create(to=…, ttlSec=300)).

Quickstart

New here? Follow QUICKSTART.md: install, get a key, send your first (free, sandbox) SMS in 5 minutes.

What can this SDK do? (function reference)

Everything hangs off one client, irnoti = Irnoti(api_key=...). Each group below is a resource (irnoti.<resource>.<function>()), and each links to its section in the API docs at irnoti.com/docs (open the docs panel and look for the section named in the "Docs section" column).

Top-level helpers (no network call):

Every function is a thin wrapper over one HTTP endpoint and returns the API's JSON as plain dict/list. Read the docstring in src/irnoti/resources.py for exact arguments, e.g. help(irnoti.sms.send).

Typical flow: lines.list() (pick a sender) → sms.quote() (see the cost) → sms.send() (with an idempotency_key) → messages.get() / webhook (delivery result). Use an irn_test_… key and line_id="sandbox" while experimenting: nothing is sent or charged.

Telegram broker

bot = irnoti.broker.create("Shop bot", botfather_token)    # scope broker.write (account owner); returns the relay `link`
irnoti.broker.request(bot["id"], "sendMessage", {"chat_id": 123, "text": "Hi"})   # scope broker.request
irnoti.broker.updates(bot["id"], limit=20)                  # pull mode
irnoti.broker.set_webhook(bot["id"], "https://example.com/tg", secret_token="s3cret")  # push mode

Behaviour shared by all irnoti SDKs

• Auth: Authorization: Bearer irn_live_…. Use an irn_test_… key with lineId: "sandbox" to try sends for free. Keys carry scopes (sms.send, sms.read, wallet.read, phonebook.read|write, bot.send|read, broker.read|write|request, verify.send|read); a missing scope is a 403.
• Money is integer Rial returned as a string ("1960") — never parse it into a float.
• Idempotency: every send takes an idempotency key; retrying with the same key never sends twice (replayed: true). Automatic retries apply only to GETs and sends that carry a key.
• Errors: one error type carrying status, the API's machine code (insufficient_balance, invalid_recipients, no_price, … — empty for plain 401/403/404) and details, with helpers such as isInsufficientBalance / isRateLimited / isUnauthenticated.
• Limits: send 600 req/min, pattern 1200 req/min per IP (429 when exceeded).
• Webhooks: verify the raw body against X-Irnoti-Signature: t=<unix>,v1=<hex> (HMAC-SHA256 of "<t>.<body>" with your whsec_… key); signatures older than 5 minutes are rejected.
• Bot-builder creation/configuration and verify settings are panel-only; Telegram broker bots can be managed through the API.

Sibling SDKs: Laravel · Node.js · Python · Go · PHP. API reference: irnoti.com/docs.

MIT licensed.