# client.assistants

> The assistants methods of the morevoice Python SDK: AI voice assistants: prompt, voice, tools and call behaviour.

AI voice assistants: prompt, voice, tools and call behaviour. These methods are on `client.assistants`, where `client` is a `MoreVoice` client (see [the Python SDK](https://docs.morevoice.ai/sdk/python/#connect)). On `AsyncMoreVoice` the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

## `create()`

**Create an assistant.** Creates an assistant. Only `name` is required; fields you leave out take their defaults (`GET /v1/assistants/{id}` shows them all).

```python
# client.assistants
def create(self, body: _m.AssistantCreateParamsInput | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Assistant
```

`client.assistants.create()` · `await async_client.assistants.create()` · `POST /assistants` · [API reference](https://docs.morevoice.ai/api/operations/assistants_create/)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | The assistant's name (yours; callers never hear it). |
| `advanced` | `object` | no | — |
| `answering_machine_detection` | `object` | no | — |
| `artifacts` | `object` | no | — |
| `end_call_message` | `string` | no | Said before the assistant ends the call. |
| `end_call_phrases` | `string[]` | no | Phrases that end the call. |
| `first_message` | `string` | no | What the assistant says first. |
| `first_message_mode` | `"assistant_speaks_first" \| "assistant_waits_for_user" \| "assistant_generates_first_message"` | no | — |
| `flow_id` | `string \| null` | no | `flow_…` ID. |
| `language` | `string` | no | The call language. |
| `llm` | `object` | no | — |
| `max_duration_seconds` | `number` | no | 10–43200 (12 hours). |
| `metadata` | `MetadataInput` | no | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `public` | `boolean` | no | Allow publishable keys (the browser widget) to call this assistant. Default false. |
| `system_prompt` | `string` | no | The instructions the model follows. |
| `tools` | `object` | no | Fields you leave out are kept. |
| `transcriber` | `object` | no | — |
| `voice` | `object` | no | — |

### Returns

`Assistant`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The assistant's ID. |
| `object` | `"assistant"` | Always `assistant`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | The assistant's name (yours; callers never hear it). |
| `language` | `string` | The call language (BCP-47, e.g. `he`, `en`). |
| `system_prompt` | `string` | The instructions the model follows. |
| `first_message` | `string` | What the assistant says first. |
| `first_message_mode` | `"assistant_speaks_first" \| "assistant_waits_for_user" \| "assistant_generates_first_message"` | Whether the assistant speaks first (`first_message`), waits for the caller, or generates its opening. |
| `voice` | `AssistantVoice` | How the assistant sounds. |
| `transcriber` | `AssistantTranscriber` | How the assistant hears. |
| `llm` | `AssistantLlm` | The language model behind the assistant. |
| `tools` | `AssistantTools` | The tools the assistant can use. |
| `flow_id` | `string \| null` | `flow_…` ID. |
| `end_call_message` | `string` | Said before the assistant ends the call. |
| `end_call_phrases` | `string[]` | Phrases that end the call when the assistant says them. |
| `max_duration_seconds` | `number` | Calls end after this long. |
| `answering_machine_detection` | `AssistantAnsweringMachineDetection` | Answering-machine detection on outbound calls. |
| `artifacts` | `AssistantArtifacts` | What is kept after a call. |
| `public` | `boolean` | Publishable keys (the browser widget) may start web calls to this assistant. |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `advanced` | `AssistantAdvanced` | Pipeline tuning. The defaults suit most assistants. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

assistant = client.assistants.create({
    "first_message": "שלום, הגעתם למרפאת השרון. איך אפשר לעזור?",
    "language": "he",
    "metadata": {
        "crm_id": "0031x00000AbCdE",
    },
    "name": "Clinic receptionist",
    "system_prompt": "You book, move and cancel appointments. Keep answers short.",
    "tools": {
        "custom": [
            {
                "description": "Find free appointment slots for a doctor and date",
                "headers": {
                    "Authorization": "Bearer crm-secret",
                },
                "name": "find_slots",
                "parameters": {
                    "properties": {
                        "date": {
                            "type": "string",
                        },
                        "doctor": {
                            "type": "string",
                        },
                    },
                    "required": [
                        "date",
                    ],
                    "type": "object",
                },
                "url": "https://crm.example.com/voice/tools",
            },
        ],
        "end_call": True,
        "transfer_call": {
            "destination": "queue:reception",
        },
    },
    "voice": {
        "provider": "gemini",
        "style": "warm",
        "voice_id": "Kore",
    },
})
print(assistant)
```

## `delete()`

**Delete an assistant.** Deletes the assistant. Past calls keep their history; inbound routes and campaigns that used it need another assistant.

```python
# client.assistants
def delete(self, id: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DeletedAssistant
```

`client.assistants.delete()` · `await async_client.assistants.delete()` · `DELETE /assistants/{id}` · [API reference](https://docs.morevoice.ai/api/operations/assistants_delete/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A assistant ID (`asst_…`). |

### Returns

`DeletedAssistant`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | A assistant ID (prefix `asst_`). |
| `object` | `"assistant"` | Always `assistant`. |
| `deleted` | `true` | — |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

deleted_assistant = client.assistants.delete("asst_7Hk2Lm9Qp")
print(deleted_assistant)
```

## `duplicate()`

**Duplicate an assistant.** Creates a copy with the same configuration, tools (including their stored headers) and metadata.

```python
# client.assistants
def duplicate(self, id: str, body: _m.AssistantsDuplicateBody | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Assistant
```

`client.assistants.duplicate()` · `await async_client.assistants.duplicate()` · `POST /assistants/{id}/duplicate` · [API reference](https://docs.morevoice.ai/api/operations/assistants_duplicate/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A assistant ID (`asst_…`). |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | no | The copy's name (default: the original's name + " (עותק)"). |

### Returns

`Assistant`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The assistant's ID. |
| `object` | `"assistant"` | Always `assistant`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | The assistant's name (yours; callers never hear it). |
| `language` | `string` | The call language (BCP-47, e.g. `he`, `en`). |
| `system_prompt` | `string` | The instructions the model follows. |
| `first_message` | `string` | What the assistant says first. |
| `first_message_mode` | `"assistant_speaks_first" \| "assistant_waits_for_user" \| "assistant_generates_first_message"` | Whether the assistant speaks first (`first_message`), waits for the caller, or generates its opening. |
| `voice` | `AssistantVoice` | How the assistant sounds. |
| `transcriber` | `AssistantTranscriber` | How the assistant hears. |
| `llm` | `AssistantLlm` | The language model behind the assistant. |
| `tools` | `AssistantTools` | The tools the assistant can use. |
| `flow_id` | `string \| null` | `flow_…` ID. |
| `end_call_message` | `string` | Said before the assistant ends the call. |
| `end_call_phrases` | `string[]` | Phrases that end the call when the assistant says them. |
| `max_duration_seconds` | `number` | Calls end after this long. |
| `answering_machine_detection` | `AssistantAnsweringMachineDetection` | Answering-machine detection on outbound calls. |
| `artifacts` | `AssistantArtifacts` | What is kept after a call. |
| `public` | `boolean` | Publishable keys (the browser widget) may start web calls to this assistant. |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `advanced` | `AssistantAdvanced` | Pipeline tuning. The defaults suit most assistants. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

assistant = client.assistants.duplicate("asst_7Hk2Lm9Qp", {
    "name": "Clinic receptionist (evening)",
})
print(assistant)
```

## `list()`

**List assistants.** Your assistants, newest first.

```python
# client.assistants
def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.Assistant]
```

`client.assistants.list()` · `await async_client.assistants.list()` · `GET /assistants` · [API reference](https://docs.morevoice.ai/api/operations/assistants_list/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |

### Returns

A page of results (`AssistantList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for assistant in client.assistants.list():
    print(assistant)
```

## `retrieve()`

**Retrieve an assistant.** Returns the assistant with every field, including the defaults of the fields you never set. Assistants are configuration shared by live and test mode.

```python
# client.assistants
def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.Assistant
```

`client.assistants.retrieve()` · `await async_client.assistants.retrieve()` · `GET /assistants/{id}` · [API reference](https://docs.morevoice.ai/api/operations/assistants_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A assistant ID (`asst_…`). |

### Returns

`Assistant`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The assistant's ID. |
| `object` | `"assistant"` | Always `assistant`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | The assistant's name (yours; callers never hear it). |
| `language` | `string` | The call language (BCP-47, e.g. `he`, `en`). |
| `system_prompt` | `string` | The instructions the model follows. |
| `first_message` | `string` | What the assistant says first. |
| `first_message_mode` | `"assistant_speaks_first" \| "assistant_waits_for_user" \| "assistant_generates_first_message"` | Whether the assistant speaks first (`first_message`), waits for the caller, or generates its opening. |
| `voice` | `AssistantVoice` | How the assistant sounds. |
| `transcriber` | `AssistantTranscriber` | How the assistant hears. |
| `llm` | `AssistantLlm` | The language model behind the assistant. |
| `tools` | `AssistantTools` | The tools the assistant can use. |
| `flow_id` | `string \| null` | `flow_…` ID. |
| `end_call_message` | `string` | Said before the assistant ends the call. |
| `end_call_phrases` | `string[]` | Phrases that end the call when the assistant says them. |
| `max_duration_seconds` | `number` | Calls end after this long. |
| `answering_machine_detection` | `AssistantAnsweringMachineDetection` | Answering-machine detection on outbound calls. |
| `artifacts` | `AssistantArtifacts` | What is kept after a call. |
| `public` | `boolean` | Publishable keys (the browser widget) may start web calls to this assistant. |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `advanced` | `AssistantAdvanced` | Pipeline tuning. The defaults suit most assistants. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

assistant = client.assistants.retrieve("asst_7Hk2Lm9Qp")
print(assistant)
```

## `update()`

**Update an assistant.** Updates the fields you send. Nested objects merge with the stored values and arrays are replaced; `tools.custom` replaces the whole list (a tool sent without `headers` keeps the stored headers of the tool with the same name). Settings that are not part of the API are kept.

```python
# client.assistants
def update(self, id: str, body: _m.AssistantUpdateParamsInput | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET) -> _m.Assistant
```

`client.assistants.update()` · `await async_client.assistants.update()` · `PATCH /assistants/{id}` · [API reference](https://docs.morevoice.ai/api/operations/assistants_update/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A assistant ID (`asst_…`). |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `advanced` | `object` | no | — |
| `answering_machine_detection` | `object` | no | — |
| `artifacts` | `object` | no | — |
| `end_call_message` | `string` | no | Said before the assistant ends the call. |
| `end_call_phrases` | `string[]` | no | Phrases that end the call. |
| `first_message` | `string` | no | What the assistant says first. |
| `first_message_mode` | `"assistant_speaks_first" \| "assistant_waits_for_user" \| "assistant_generates_first_message"` | no | — |
| `flow_id` | `string \| null` | no | `flow_…` ID. |
| `language` | `string` | no | The call language. |
| `llm` | `object` | no | — |
| `max_duration_seconds` | `number` | no | 10–43200 (12 hours). |
| `metadata` | `MetadataInput` | no | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `name` | `string` | no | The assistant's name (yours; callers never hear it). |
| `public` | `boolean` | no | Allow publishable keys (the browser widget) to call this assistant. Default false. |
| `system_prompt` | `string` | no | The instructions the model follows. |
| `tools` | `object` | no | Fields you leave out are kept. |
| `transcriber` | `object` | no | — |
| `voice` | `object` | no | — |

### Returns

`Assistant`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The assistant's ID. |
| `object` | `"assistant"` | Always `assistant`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | The assistant's name (yours; callers never hear it). |
| `language` | `string` | The call language (BCP-47, e.g. `he`, `en`). |
| `system_prompt` | `string` | The instructions the model follows. |
| `first_message` | `string` | What the assistant says first. |
| `first_message_mode` | `"assistant_speaks_first" \| "assistant_waits_for_user" \| "assistant_generates_first_message"` | Whether the assistant speaks first (`first_message`), waits for the caller, or generates its opening. |
| `voice` | `AssistantVoice` | How the assistant sounds. |
| `transcriber` | `AssistantTranscriber` | How the assistant hears. |
| `llm` | `AssistantLlm` | The language model behind the assistant. |
| `tools` | `AssistantTools` | The tools the assistant can use. |
| `flow_id` | `string \| null` | `flow_…` ID. |
| `end_call_message` | `string` | Said before the assistant ends the call. |
| `end_call_phrases` | `string[]` | Phrases that end the call when the assistant says them. |
| `max_duration_seconds` | `number` | Calls end after this long. |
| `answering_machine_detection` | `AssistantAnsweringMachineDetection` | Answering-machine detection on outbound calls. |
| `artifacts` | `AssistantArtifacts` | What is kept after a call. |
| `public` | `boolean` | Publishable keys (the browser widget) may start web calls to this assistant. |
| `metadata` | `Metadata` | Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent. |
| `advanced` | `AssistantAdvanced` | Pipeline tuning. The defaults suit most assistants. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

assistant = client.assistants.update("asst_7Hk2Lm9Qp", {
    "advanced": {
        "stop_speaking_plan": {
            "num_words": 2,
        },
    },
    "metadata": {
        "stage": "beta",
    },
    "voice": {
        "style": "calm and reassuring",
    },
})
print(assistant)
```