calldesktech

Official Python client SDK for the CallDeskTech API — build, publish and operate voice agents.

Install

pip install -e .

(Not yet published to PyPI — install from a local clone or a git URL for now: pip install git+https://github.com/calldesktech/calldesktech-python.)

Requires Python 3.9+. Only dependency is requests.

Quickstart

Create an API key in your CallDeskTech workspace (Settings → API Keys), then:

from calldesktech import CallDeskTech, CallDeskTechError

client = CallDeskTech(api_key="cdk_live_...")

# Every key is pinned to one workspace.
me = client.me()
tenant_id = me.tenant_id

# Create an agent from a built-in template.
templates = client.list_agent_templates()
result = client.create_agent_from_template(
    tenant_id,
    {
        "templateId": templates[0].id,
        "name": "Front Desk",
        "voiceEngine": "poc",
        "variables": {"business_name": "Acme Dental"},
    },
)
print(result.agent_id, result.version_id)

# Promote that version into production, then route a number to the
# environment (not a specific version) so future promotions pick up
# automatically.
environments = client.list_environments(result.agent_id)
production = next(e for e in environments if e.name == "production")
client.promote_environment(result.agent_id, "production", version_id=result.version_id)

numbers = client.list_phone_numbers(tenant_id)
client.route_phone_number(
    numbers[0].id,
    direction="outbound",
    environment_id=production.id,
)

# Place a call (this incurs real cost — only call this when you mean it).
try:
    call = client.place_call(numbers[0].id, to_number="+15551234567")
    print(call.sid)
except CallDeskTechError as e:
    print(f"call failed: {e.status_code} {e.message}")

Coverage

• Account: me()
• Agents: list/create/get/rename/delete, versions (list/publish), templates (list/create-from-template)
• Environments: list, promote (staging/production)
• Subflows: list/create/get/update/delete
• Knowledge bases: list/create/update/delete, Q&A items (list/add)
• Phone numbers: list, routing (by agent version or environment)
• Calls: place, list, get, recording
• Batch calls: list/create/get/run (CSV + dynamic variables, scheduling, call time windows)
• Webhooks: list/create/update/delete/test
• Contacts: list
• Analytics & QA: analytics, QA overview, test cases (list/create/run), Copilot suggestions

Errors

Every non-2xx response raises CallDeskTechError with .status_code and .message (the API's own error text when present).

Types

Request bodies are TypedDicts and responses are dataclasses (see calldesktech.types), inferred from the live OpenAPI spec at https://calldesk.tech/api/v1/openapi.json. Dataclasses keep the original payload on .raw in case a field isn't modeled yet.