siptel 0.1.0

Official Python SDK for the SIPTEL REST API (voice, AI agents, SMS, numbers, SIP).

SIPTEL Python SDK

Official Python client for the SIPTEL REST API — AI voice agents, programmable Voice API, SMS, phone numbers, and SIP trunks.

Install

pip install siptel

Quick start

Set your API key (from the dashboard):

export SIPTEL_API_KEY="sk_live_..."   # Linux/macOS
# set SIPTEL_API_KEY=sk_live_...      # Windows CMD

from siptel import Client

client = Client()

# List AI agents
agents = client.agent.list_agents()

# Outbound AI agent call (see docs for all parameters)
result = client.agent.create_call(
    phone_number="[phone]",
    caller_id="[phone]",
    voice="Rachel",
    record=True,
    voicemail_action="hangup",
    greeting_message="Hello!",
    task_prompt="You are a helpful assistant.",
    language="en-US",
)

# Voice API
call = client.voice.retrieve_call("CA20251109171204335505")

# SMS
client.sms.send(
    app_id="...",
    phone_number="[phone]",
    sender_id="SIPTEL",
    text="Hello from SIPTEL",
)

# Numbers
numbers = client.numbers.list()

Authentication

All requests use Authorization: Bearer <api_key>. You can pass the key explicitly:

client = Client(api_key="sk_live_...")

Configuration

Option	Environment variable	Default
API key	SIPTEL_API_KEY	—
Base URL	SIPTEL_BASE_URL (not auto-read; pass base_url=)	https://api.siptel.ai
User-Agent	SIPTEL_USER_AGENT	SiptelPythonSDK/0.1

client = Client(
    api_key="sk_live_...",
    base_url="https://api.siptel.ai",
    timeout=60.0,
)

Resource layout (Telnyx-style)

Namespace	API area
client.agent	AI agent calls, list/get agents
client.voice	Voice API (play, gather, transfer, hangup, call status)
client.sip	SIP users / trunks
client.sms	Send SMS, list SMS apps
client.numbers	List/search/purchase/assign numbers

Errors

The SDK raises typed exceptions on HTTP error responses:

from siptel import (
    Client,
    AuthenticationError,
    InvalidRequestError,
    NotFoundError,
    PaymentRequiredError,
    RateLimitError,
    APIError,
)

try:
    client.sms.send(...)
except InvalidRequestError as e:
    print(e.status_code, e.response_body)

Low-level API

For endpoints not yet wrapped, use the escape hatch:

client.post("/v1/agent/call", json={...})
client.get("/v1/custom/path")

Requirements

• Python 3.10+
• requests

Development

cd sdk/siptel-python
pip install -e ".[dev]"
ruff check src
pytest

GitHub

• CI: .github/workflows/siptel-python-ci.yml runs Ruff + pytest on changes under sdk/siptel-python/.
• PyPI: .github/workflows/workflow.yml publishes on tags v* (e.g. v0.1.0) using Trusted Publishing (OIDC — no long-lived API token in GitHub secrets).

siptelai/siptel repo

Push this repo (or mirror the SDK + workflows there). The publish workflow expects the layout sdk/siptel-python/ at the repo root. PyPI pending publisher must list workflow file: workflow.yml and repository: siptelai/siptel.

Standalone SDK-only repo

If the repo root is the Python package (no sdk/ folder), change working-directory and packages-dir in workflow.yml to match (often . and dist/).

Publishing to PyPI (manual)

1. Bump version in pyproject.toml and siptel.__version__ in src/siptel/__init__.py.
2. Build: python -m build
3. Upload: python -m twine upload dist/* (PyPI API token as password, user __token__).

PyPI project name: the distribution is named siptel. If that name is taken on PyPI, change [project] name in pyproject.toml (e.g. siptel-ai) while keeping packages / import name as needed.

License

MIT — see LICENSE.