# client.connections

> The connections methods of the morevoice Python SDK: SIP trunks connecting MoreVoice to your carriers.

SIP trunks connecting MoreVoice to your carriers. These methods are on `client.connections`, 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 a connection.** Adds a SIP connection to your carrier: a trunk the carrier sends calls to, or a registration account MoreVoice registers like a desk phone. `password` is write-only. New inbound calls are accepted only from the connection's host and its `inbound_acl`. Live mode only: a test key answers `403` with the code `live_only`.

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

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | — |
| `answer_inbound` | `boolean` | no | — |
| `auth_username` | `string` | no | — |
| `backend` | `"native" \| "freeswitch"` | no | — |
| `caller_ids` | `string[]` | no | — |
| `codecs` | `("pcma" \| "pcmu")[]` | no | — |
| `default_caller_id` | `string \| ""` | no | The caller ID used when a call names none (empty: none). |
| `display_name` | `string` | no | — |
| `enabled` | `boolean` | no | — |
| `host` | `string` | no | The carrier's SIP host (a name or an IP address). |
| `inbound_acl` | `string[]` | no | — |
| `inbound_assistant_id` | `string \| null` | no | `asst_…` ID. |
| `inbound_reserve_pct` | `integer` | no | — |
| `max_channels` | `integer` | no | — |
| `max_cps` | `integer` | no | — |
| `overflow_policy` | `"busy" \| "unavailable"` | no | — |
| `password` | `string \| null` | no | Write-only. A string sets it, null removes it; leave it out to keep the stored one. |
| `port` | `integer` | no | — |
| `register` | `boolean` | no | — |
| `register_expires_seconds` | `integer` | no | — |
| `transport` | `"udp"` | no | — |
| `type` | `"registration" \| "trunk"` | no | — |
| `username` | `string` | no | — |

### Returns

`Connection`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The connection's ID. |
| `object` | `"connection"` | Always `connection`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | Disabled connections neither register nor carry calls. |
| `type` | `"registration" \| "trunk"` | `registration`: registers like a phone/extension. `trunk`: a carrier trunk (IP or credential authentication). |
| `backend` | `"native" \| "freeswitch"` | `native`: the platform's own SIP stack. `freeswitch`: FreeSWITCH in front. |
| `host` | `string` | The carrier's SIP host. |
| `port` | `integer` | — |
| `transport` | `"udp"` | Always `udp`. |
| `username` | `string` | — |
| `auth_username` | `string` | The authentication user, when it differs from `username`. |
| `password_set` | `boolean` | Whether a password is stored. Passwords are write-only. |
| `display_name` | `string` | — |
| `register` | `boolean` | Send REGISTER to the host. |
| `register_expires_seconds` | `integer` | — |
| `caller_ids` | `string[]` | Numbers this connection may present as caller ID. |
| `default_caller_id` | `string` | The caller ID used when a call names none. |
| `max_channels` | `integer` | Simultaneous calls (0: unlimited). |
| `max_cps` | `integer` | New outbound calls per second (0: unlimited). |
| `inbound_reserve_pct` | `integer` | Share of `max_channels` outbound campaigns never use, kept for inbound calls. |
| `answer_inbound` | `boolean` | Answer inbound calls on this connection. |
| `inbound_assistant_id` | `string \| null` | `asst_…` ID. |
| `inbound_acl` | `string[]` | Trunks: extra source IPs / CIDRs allowed to send calls (the host's addresses always are). |
| `overflow_policy` | `"busy" \| "unavailable"` | When the connection is full: `busy` (486) or `unavailable` (503, lets a carrier fail over). |
| `codecs` | `("pcma" \| "pcmu")[]` | Audio codecs, in preference order. |
| `status` | `ConnectionStatus` | The connection's live state. |
| `active_calls` | `integer` | Calls on the connection right now. |
| `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

connection = client.connections.create({
    "caller_ids": [
        "+97231234567",
    ],
    "default_caller_id": "+97231234567",
    "host": "sip.carrier.example.com",
    "inbound_acl": [
        "198.51.100.0/24",
    ],
    "max_channels": 30,
    "max_cps": 5,
    "name": "Main trunk",
    "register": False,
    "type": "trunk",
})
print(connection)
```

## `delete()`

**Delete a connection.** Deletes the connection. Refused (409) while it carries calls.

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

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

### Parameters

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

### Returns

`DeletedConnection`:

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

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

deleted_connection = client.connections.delete("conn_7Hk2Lm9Qp")
print(deleted_connection)
```

## `list()`

**List connections.** Lists your SIP connections, oldest first, with their registration status and the calls on them now. Passwords are never returned. Live mode only: a test key answers `403` with the code `live_only`.

```python
# client.connections
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.Connection]
```

`client.connections.list()` · `await async_client.connections.list()` · `GET /connections` · [API reference](https://docs.morevoice.ai/api/operations/connections_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 (`ConnectionList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for connection in client.connections.list():
    print(connection)
```

## `register()`

**Re-register a connection.** Sends a fresh REGISTER now (FreeSWITCH connections re-register their gateway). The answer is the state right after the request.

```python
# client.connections
def register(self, id: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.ConnectionRegistration
```

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

### Parameters

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

### Returns

`ConnectionRegistration`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"connection_registration"` | Always `connection_registration`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `connection_id` | `string` | A connection ID (prefix `conn_`). |
| `status` | `ConnectionStatus` | The connection's live state. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

connection_registration = client.connections.register("conn_7Hk2Lm9Qp")
print(connection_registration)
```

## `retrieve()`

**Retrieve a connection.** Returns a SIP connection with its limits, its registration status and the calls on it now. The password is never returned (`password_set` says whether one is stored). Live mode only.

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

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

### Parameters

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

### Returns

`Connection`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The connection's ID. |
| `object` | `"connection"` | Always `connection`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | Disabled connections neither register nor carry calls. |
| `type` | `"registration" \| "trunk"` | `registration`: registers like a phone/extension. `trunk`: a carrier trunk (IP or credential authentication). |
| `backend` | `"native" \| "freeswitch"` | `native`: the platform's own SIP stack. `freeswitch`: FreeSWITCH in front. |
| `host` | `string` | The carrier's SIP host. |
| `port` | `integer` | — |
| `transport` | `"udp"` | Always `udp`. |
| `username` | `string` | — |
| `auth_username` | `string` | The authentication user, when it differs from `username`. |
| `password_set` | `boolean` | Whether a password is stored. Passwords are write-only. |
| `display_name` | `string` | — |
| `register` | `boolean` | Send REGISTER to the host. |
| `register_expires_seconds` | `integer` | — |
| `caller_ids` | `string[]` | Numbers this connection may present as caller ID. |
| `default_caller_id` | `string` | The caller ID used when a call names none. |
| `max_channels` | `integer` | Simultaneous calls (0: unlimited). |
| `max_cps` | `integer` | New outbound calls per second (0: unlimited). |
| `inbound_reserve_pct` | `integer` | Share of `max_channels` outbound campaigns never use, kept for inbound calls. |
| `answer_inbound` | `boolean` | Answer inbound calls on this connection. |
| `inbound_assistant_id` | `string \| null` | `asst_…` ID. |
| `inbound_acl` | `string[]` | Trunks: extra source IPs / CIDRs allowed to send calls (the host's addresses always are). |
| `overflow_policy` | `"busy" \| "unavailable"` | When the connection is full: `busy` (486) or `unavailable` (503, lets a carrier fail over). |
| `codecs` | `("pcma" \| "pcmu")[]` | Audio codecs, in preference order. |
| `status` | `ConnectionStatus` | The connection's live state. |
| `active_calls` | `integer` | Calls on the connection right now. |
| `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

connection = client.connections.retrieve("conn_7Hk2Lm9Qp")
print(connection)
```

## `update()`

**Update a connection.** Changes the fields you send; the rest is kept. `password` is write-only: a string replaces it, null removes it.

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

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

### Parameters

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `answer_inbound` | `boolean` | no | — |
| `auth_username` | `string` | no | — |
| `backend` | `"native" \| "freeswitch"` | no | — |
| `caller_ids` | `string[]` | no | — |
| `codecs` | `("pcma" \| "pcmu")[]` | no | — |
| `default_caller_id` | `string \| ""` | no | The caller ID used when a call names none (empty: none). |
| `display_name` | `string` | no | — |
| `enabled` | `boolean` | no | — |
| `host` | `string` | no | The carrier's SIP host (a name or an IP address). |
| `inbound_acl` | `string[]` | no | — |
| `inbound_assistant_id` | `string \| null` | no | `asst_…` ID. |
| `inbound_reserve_pct` | `integer` | no | — |
| `max_channels` | `integer` | no | — |
| `max_cps` | `integer` | no | — |
| `name` | `string` | no | — |
| `overflow_policy` | `"busy" \| "unavailable"` | no | — |
| `password` | `string \| null` | no | Write-only. A string sets it, null removes it; leave it out to keep the stored one. |
| `port` | `integer` | no | — |
| `register` | `boolean` | no | — |
| `register_expires_seconds` | `integer` | no | — |
| `transport` | `"udp"` | no | — |
| `type` | `"registration" \| "trunk"` | no | — |
| `username` | `string` | no | — |

### Returns

`Connection`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The connection's ID. |
| `object` | `"connection"` | Always `connection`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | Disabled connections neither register nor carry calls. |
| `type` | `"registration" \| "trunk"` | `registration`: registers like a phone/extension. `trunk`: a carrier trunk (IP or credential authentication). |
| `backend` | `"native" \| "freeswitch"` | `native`: the platform's own SIP stack. `freeswitch`: FreeSWITCH in front. |
| `host` | `string` | The carrier's SIP host. |
| `port` | `integer` | — |
| `transport` | `"udp"` | Always `udp`. |
| `username` | `string` | — |
| `auth_username` | `string` | The authentication user, when it differs from `username`. |
| `password_set` | `boolean` | Whether a password is stored. Passwords are write-only. |
| `display_name` | `string` | — |
| `register` | `boolean` | Send REGISTER to the host. |
| `register_expires_seconds` | `integer` | — |
| `caller_ids` | `string[]` | Numbers this connection may present as caller ID. |
| `default_caller_id` | `string` | The caller ID used when a call names none. |
| `max_channels` | `integer` | Simultaneous calls (0: unlimited). |
| `max_cps` | `integer` | New outbound calls per second (0: unlimited). |
| `inbound_reserve_pct` | `integer` | Share of `max_channels` outbound campaigns never use, kept for inbound calls. |
| `answer_inbound` | `boolean` | Answer inbound calls on this connection. |
| `inbound_assistant_id` | `string \| null` | `asst_…` ID. |
| `inbound_acl` | `string[]` | Trunks: extra source IPs / CIDRs allowed to send calls (the host's addresses always are). |
| `overflow_policy` | `"busy" \| "unavailable"` | When the connection is full: `busy` (486) or `unavailable` (503, lets a carrier fail over). |
| `codecs` | `("pcma" \| "pcmu")[]` | Audio codecs, in preference order. |
| `status` | `ConnectionStatus` | The connection's live state. |
| `active_calls` | `integer` | Calls on the connection right now. |
| `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

connection = client.connections.update("conn_7Hk2Lm9Qp", {
    "max_cps": 10,
    "password": "n3w-pa55",
})
print(connection)
```