ahs-cti-api-sdk 0.1.0a3

Python SDK for the AHS CTI Platform

AHS CTI Python SDK

Python SDK for the AHS CTI Platform — initiate and control outbound calls via REST API.

Requirements: Python ≥ 3.9 · httpx ≥ 0.25

---

Installation

pip install ahs-cti-api-sdk

---

Quick Start

API-Key Authentication (recommended for server integrations)

from ahs_cti import CtiClient

with CtiClient(base_url="https://cti.example.com", api_key="ctsk_...", tenant_id=1) as client:
    result = client.calls.dial("[phone]")
    print(result.call_id)   # save this for end_call

    end = client.calls.end_call(
        result.call_id,
        disposition="INTERESTED",
        list_comments="Customer wants a demo next week",
    )
    print(end.duration)

Credential Authentication

from ahs_cti import CtiClient

with CtiClient(base_url="https://cti.example.com", user_id="agent1", password="secret") as client:
    result = client.calls.dial("[phone]", caller_id="AH2007C")

Async Client

import asyncio
from ahs_cti import AsyncCtiClient

async def main():
    async with AsyncCtiClient(base_url="https://cti.example.com", api_key="ctsk_...") as client:
        result = await client.calls.dial("[phone]")
        print(result.call_id)

asyncio.run(main())

---

ClientConfig Reference

For full control over transport settings, use ClientConfig:

from ahs_cti import CtiClient, ClientConfig

config = ClientConfig(
    base_url="https://cti.example.com",
    timeout=15.0,
    verify_ssl=False,   # for self-signed certificates
    max_retries=5,
)

with CtiClient(config=config, api_key="ctsk_...") as client:
    result = client.calls.dial("[phone]")

Parameter	Type	Default	Description
base_url	str	required	Root URL of the CTI platform
timeout	float	30.0	Request timeout in seconds
verify_ssl	bool	True	Set False for self-signed certs
max_retries	int	3	Retry attempts on 5xx / network errors

---

Error Handling

from ahs_cti import CtiClient, CtiAuthError, CtiApiError, CtiRetryExhaustedError

with CtiClient(...) as client:
    try:
        result = client.calls.dial("[phone]")
    except CtiAuthError:
        # Invalid or expired API key / credentials
        print("Authentication failed")
    except CtiRetryExhaustedError as e:
        # All retry attempts failed (5xx or network)
        print(f"Failed after {e.attempts} attempts: {e.last_exc}")
    except CtiApiError as e:
        # Any other API error (400, 404, 422 …)
        print(f"API error [{e.status_code}]: {e}")

Exception Hierarchy

CtiError
├── CtiAuthError          — 401 / login failure
└── CtiApiError           — 4xx / 5xx from the platform
    └── CtiRetryExhaustedError  — all retries exhausted

---

Retry Behaviour

The SDK automatically retries on 500, 502, 503, 504 responses and transient network errors (ConnectError, TimeoutException). Retries use exponential backoff:

Attempt	Delay
1st (initial)	none
2nd retry	2 s
3rd retry	4 s
4th retry	8 s

Set max_retries=0 in ClientConfig to disable retries entirely.

---

Self-Signed Certificates

Internal / staging servers often use self-signed TLS certificates. Pass verify_ssl=False:

client = CtiClient(base_url="https://192.168.1.10:8082", api_key="ctsk_...", verify_ssl=False)

Do not disable SSL verification in production.