Skip to content
MoreVoiceDevelopers

client.connections

SIP trunks connecting MoreVoice to your carriers. These methods are on client.connections, where client is a MoreVoice client (see the Python SDK). 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()

Section titled “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.

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

Request body

Section titled “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

Section titled “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

Section titled “Example”
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()

Section titled “delete()”

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

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

Parameters

Section titled “Parameters”
Name Type Required Description
id str yes A connection ID (conn_…).

Returns

Section titled “Returns”

DeletedConnection:

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

Example

Section titled “Example”
from morevoice import MoreVoice


client = MoreVoice()  # MOREVOICE_API_KEY from the environment


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

list()

Section titled “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.

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

Parameters

Section titled “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

Section titled “Returns”

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

Example

Section titled “Example”
from morevoice import MoreVoice


client = MoreVoice()  # MOREVOICE_API_KEY from the environment


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

register()

Section titled “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.

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

Parameters

Section titled “Parameters”
Name Type Required Description
id str yes A connection ID (conn_…).

Returns

Section titled “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

Section titled “Example”
from morevoice import MoreVoice


client = MoreVoice()  # MOREVOICE_API_KEY from the environment


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

retrieve()

Section titled “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.

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

Parameters

Section titled “Parameters”
Name Type Required Description
id str yes A connection ID (conn_…).

Returns

Section titled “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

Section titled “Example”
from morevoice import MoreVoice


client = MoreVoice()  # MOREVOICE_API_KEY from the environment


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

update()

Section titled “update()”

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

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

Parameters

Section titled “Parameters”
Name Type Required Description
id str yes A connection ID (conn_…).

Request body

Section titled “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

Section titled “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

Section titled “Example”
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)