Metadata-Version: 2.4
Name: morevoice
Version: 1.0.0
Summary: The official MoreVoice SDK for Python: AI voice agents, calls, campaigns and webhooks (sync and async).
Project-URL: Homepage, https://docs.morevoice.ai
Project-URL: Documentation, https://docs.morevoice.ai/sdk/python/
Author: MoreVision Advanced Solutions Ltd.
License-Expression: MIT
License-File: LICENSE
Keywords: ai,api,morevoice,sdk,telephony,voice
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Telephony
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx<0.29.0,>=0.23.1
Description-Content-Type: text/markdown

# morevoice

The official Python SDK for the [MoreVoice](https://docs.morevoice.ai) API: AI voice agents, calls, campaigns, webhooks
and custom tools. It has a sync client (`MoreVoice`) and an asyncio one (`AsyncMoreVoice`).

- Every `/v1` operation has a typed method, generated from the API's OpenAPI description.
- Retries with automatic idempotency keys, typed errors, auto-pagination, Server-Sent Event streams and webhook
  verification are built in.
- Python 3.11 and later. The only dependencies are `httpx` and `attrs`.

## Install

```sh
pip install morevoice
```

## Connect

Create an API key in the MoreVoice dashboard under **Developers › API keys**. Keep it in the `MOREVOICE_API_KEY`
environment variable. Use a test-mode key (`mv_test_…`) while you build: test mode never reaches a real phone. API
keys are secrets, for your server only.

The public API domain is not live yet. Until it is, also set `MOREVOICE_BASE_URL` to the address of your MoreVoice
workspace, the one your team signs in at:

```sh
export MOREVOICE_API_KEY=mv_test_sk_...
export MOREVOICE_BASE_URL=https://voice.example.com   # your MoreVoice workspace; the SDK adds /v1
```

The REST API is in beta, and it is switched on per organisation. Ask your MoreVoice contact to switch it on for yours.

## Quickstart

```python
from morevoice import MoreVoice

client = MoreVoice()  # reads MOREVOICE_API_KEY and MOREVOICE_BASE_URL

# Check the key: which organisation, and which mode.
me = client.whoami.retrieve()
print(f"Connected to {me.org_id} in {'live' if me.livemode else 'test'} mode")

# Place a call with one of your assistants. A test key never dials: the call runs on simulated providers.
call = client.calls.create({"to": "+972501234567", "assistant_id": "asst_...", "purpose": "service"})
ended = client.calls.wait_until_ended(call.id)
print(ended.id, ended.status)

# List methods page automatically.
for c in client.calls.list(status="ended"):
    print(c.id)
```

You can also pass the settings in code: `MoreVoice(api_key=..., base_url=...)`.

### Async

```python
import asyncio

from morevoice import AsyncMoreVoice


async def main() -> None:
    async with AsyncMoreVoice() as client:
        me = await client.whoami.retrieve()
        print(me.org_id)


asyncio.run(main())
```

### Verify a webhook

```python
import os

from morevoice import webhooks

# payload: the request body exactly as received (bytes or str), before any JSON parsing.
event = webhooks.construct_event(payload, request.headers, os.environ["MOREVOICE_WEBHOOK_SECRET"])
if event["type"] == "call.ended":
    ...
```

### Handle errors

```python
from morevoice import MoreVoice, NotFoundError

try:
    MoreVoice().calls.retrieve("call_missing")
except NotFoundError as err:
    print("no such call", err.request_id)
```

## Documentation

- [Python SDK guide](https://docs.morevoice.ai/sdk/python/): every resource and helper.
- [Quickstart](https://docs.morevoice.ai/get-started/quickstart/) and [authentication](https://docs.morevoice.ai/get-started/authentication/).
- [API reference](https://docs.morevoice.ai/api/).

## Versioning and support

The SDK follows [Semantic Versioning](https://semver.org). Each release speaks the API version its models describe and
sends it as the `MoreVoice-Version` header. To pin another version, use `MoreVoice(version=...)`. Each major version gets
fixes for 12 months after the next major is released.

## License

MIT © MoreVision Advanced Solutions Ltd. See `LICENSE`.
