herosms 0.1.0

Async Python client for HeroSMS (sms-activate.ru compatible) API

herosms

Async and sync Python client for HeroSMS (SMS-Activate compatible API).

Features

• Async-first client with context-manager support
• Synchronous wrapper for non-async projects
• Activation lifecycle helpers (create, wait, resend, complete, cancel)
• Rent APIs support
• Reference data helpers (countries, services, operators, prices)
• Typed models with Pydantic v2
• Custom exception hierarchy
• Webhook payload parsing for incoming SMS events

Installation

pip install herosms

For development:

uv sync --extra dev

Quickstart (async)

import asyncio

from herosms import HeroSMSClient


async def main() -> None:
    async with HeroSMSClient(api_key="YOUR_API_KEY") as client:
        balance = await client.get_balance()
        print(f"Balance: {balance}")

        async with await client.activations.create(service="tg", country=6) as activation:
            status = await activation.wait_for_sms(timeout=120)
            print("Code:", status.code)
            await activation.complete()


asyncio.run(main())

Quickstart (sync)

from herosms import SyncHeroSMSClient


with SyncHeroSMSClient(api_key="YOUR_API_KEY") as client:
    balance = client.get_balance()
    print(f"Balance: {balance}")

Activation lifecycle

Create activation and wait for code:

async with await client.activations.create(service="tg", country=6) as activation:
    status = await activation.wait_for_sms(timeout=120)
    print(status.code)

Request another SMS:

await activation.request_sms()

Complete or cancel:

await activation.complete()
# or
await activation.cancel()

Get all OTP messages for activation:

messages = await activation.get_all_sms()

Legacy status endpoint (getStatus)

Use get_status_v1 if you need raw text-compatible status values from legacy integrations:

raw_status = await client.get_status_v1(activation_id=123456)
print(raw_status)  # e.g. STATUS_WAIT_CODE or STATUS_OK:1234

Sync variant:

raw_status = client.get_status_v1(activation_id=123456)

Rent flow

Check availability:

availability = await client.get_rent_availability(service="tg", country=6)
print(availability)

Rent a number:

rent_activation = await client.rent_number(service="tg", country=6, duration=2)
print(rent_activation.phone)

Sync variants are available with the same method names.

Reference data APIs

countries = await client.get_countries()
services = await client.get_services(country=6)
operators = await client.get_operators(country=6)
prices = await client.get_prices(service="tg", country=6)
top = await client.get_top_countries(service="tg", by_rank=True)

Error handling

All library exceptions inherit from HeroSMSError.

from herosms import HeroSMSError


try:
    ...
except HeroSMSError as exc:
    print(f"HeroSMS error: {exc}")

Webhook payload parsing (smsIncoming)

Parse and validate incoming webhook payload with Pydantic model:

from herosms import WebhookSMSIncoming

payload = {
    "activationId": "635468024",
    "service": "tg",
    "text": "Telegram code 123456",
    "code": "123456",
    "country": 6,
    "receivedAt": "2026-02-16T12:36:59+03:00",
}

event = WebhookSMSIncoming.model_validate(payload)
print(event.activation_id, event.code)

API compatibility note

HeroSMS is compatible with SMS-Activate-style API actions. This library targets HeroSMS endpoints while preserving familiar SMS-Activate action semantics.