mv.connections

SIP trunks connecting MoreVoice to your carriers. These methods are on mv.connections, where mv is your client (see the Node.js SDK). Each one returns the response object and throws when the API answers with an error.

`create()`

Create a connection.

mv.connections.create(body: ConnectionsCreateData["body"], options?: RequestOptions): Promise<ConnectionsCreateResponse>

POST /connections · API reference

Parameters

Name	Type	Required	Description
`body.name`	`string`	yes
`body.answer_inbound`	`boolean`	no
`body.auth_username`	`string`	no
`body.backend`	`"native" \| "freeswitch"`	no
`body.caller_ids`	`string[]`	no
`body.codecs`	`("pcma" \| "pcmu")[]`	no
`body.default_caller_id`	`string \| ""`	no	The caller ID used when a call names none (empty: none).
`body.display_name`	`string`	no
`body.enabled`	`boolean`	no
`body.host`	`string`	no	The carrier’s SIP host (a name or an IP address).
`body.inbound_acl`	`string[]`	no
`body.inbound_assistant_id`	`string \| null`	no	`asst_…` ID.
`body.inbound_reserve_pct`	`integer`	no
`body.max_channels`	`integer`	no
`body.max_cps`	`integer`	no
`body.overflow_policy`	`"busy" \| "unavailable"`	no
`body.password`	`string \| null`	no	Write-only. A string sets it, null removes it; leave it out to keep the stored one.
`body.port`	`integer`	no
`body.register`	`boolean`	no
`body.register_expires_seconds`	`integer`	no
`body.transport`	`"udp"`	no
`body.type`	`"registration" \| "trunk"`	no
`body.username`	`string`	no
`options.headers["MoreVoice-Version"]`	`string`	no	The API version to use for this request. Defaults to the version the API key is pinned to.
`options.headers["Idempotency-Key"]`	`string`	no	A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
`options`	`RequestOptions`	no	`idempotencyKey`, extra `headers` and an abort `signal`: see retries and idempotency.

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

import { createClient, createResources } from "@morevoice/sdk";

const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});

const connection = await mv.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",
});
console.log(connection);

`delete()`

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

mv.connections.delete(id: ConnectionsDeleteData["path"]["id"], options?: RequestOptions): Promise<ConnectionsDeleteResponse>

DELETE /connections/{id} · API reference

Parameters

Name	Type	Required	Description
`id`	`string`	yes	A connection ID (`conn_…`).
`options.headers["MoreVoice-Version"]`	`string`	no	The API version to use for this request. Defaults to the version the API key is pinned to.
`options.headers["Idempotency-Key"]`	`string`	no	A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
`options`	`RequestOptions`	no	`idempotencyKey`, extra `headers` and an abort `signal`: see retries and idempotency.

Returns

DeletedConnection:

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

Example

import { createClient, createResources } from "@morevoice/sdk";

const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});

const deletedConnection = await mv.connections.delete("conn_rtcFZ4v7Gg3mfomNppGQci");
console.log(deletedConnection);

`list()`

List connections.

mv.connections.list(query?: NonNullable<ConnectionsListData["query"]>, options?: RequestOptions): PagedList<ConnectionsListResponse["data"][number], NonNullable<ConnectionsListData["query"]>>

GET /connections · API reference

Parameters

Name	Type	Required	Description
`query.limit`	`integer`	no	How many objects to return, 1–100 (default 20).
`query.starting_after`	`string`	no	A cursor (`next_cursor`) or object ID: return the objects after it (older).
`query.ending_before`	`string`	no	A cursor or object ID: return the objects before it (newer).
`options.headers["MoreVoice-Version"]`	`string`	no	The API version to use for this request. Defaults to the version the API key is pinned to.
`options`	`RequestOptions`	no	`idempotencyKey`, extra `headers` and an abort `signal`: see retries and idempotency.

Returns

A PagedList: await it for the first page, for await it for every item.

Example

import { createClient, createResources } from "@morevoice/sdk";

const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});

for await (const connection of mv.connections.list()) {
  console.log(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.

mv.connections.register(id: ConnectionsRegisterData["path"]["id"], options?: RequestOptions): Promise<ConnectionsRegisterResponse>

POST /connections/{id}/register · API reference

Parameters

Name	Type	Required	Description
`id`	`string`	yes	A connection ID (`conn_…`).
`options.headers["MoreVoice-Version"]`	`string`	no	The API version to use for this request. Defaults to the version the API key is pinned to.
`options.headers["Idempotency-Key"]`	`string`	no	A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
`options`	`RequestOptions`	no	`idempotencyKey`, extra `headers` and an abort `signal`: see retries and idempotency.

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

import { createClient, createResources } from "@morevoice/sdk";

const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});

const connectionRegistration = await mv.connections.register("conn_rtcFZ4v7Gg3mfomNppGQci");
console.log(connectionRegistration);

`retrieve()`

Retrieve a connection.

mv.connections.retrieve(id: ConnectionsRetrieveData["path"]["id"], options?: RequestOptions): Promise<ConnectionsRetrieveResponse>

GET /connections/{id} · API reference

Parameters

Name	Type	Required	Description
`id`	`string`	yes	A connection ID (`conn_…`).
`options.headers["MoreVoice-Version"]`	`string`	no	The API version to use for this request. Defaults to the version the API key is pinned to.
`options`	`RequestOptions`	no	`idempotencyKey`, extra `headers` and an abort `signal`: see retries and idempotency.

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

import { createClient, createResources } from "@morevoice/sdk";

const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});

const connection = await mv.connections.retrieve("conn_rtcFZ4v7Gg3mfomNppGQci");
console.log(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.

mv.connections.update(id: ConnectionsUpdateData["path"]["id"], body?: ConnectionsUpdateData["body"], options?: RequestOptions): Promise<ConnectionsUpdateResponse>

PATCH /connections/{id} · API reference

Parameters

Name	Type	Required	Description
`id`	`string`	yes	A connection ID (`conn_…`).
`body.answer_inbound`	`boolean`	no
`body.auth_username`	`string`	no
`body.backend`	`"native" \| "freeswitch"`	no
`body.caller_ids`	`string[]`	no
`body.codecs`	`("pcma" \| "pcmu")[]`	no
`body.default_caller_id`	`string \| ""`	no	The caller ID used when a call names none (empty: none).
`body.display_name`	`string`	no
`body.enabled`	`boolean`	no
`body.host`	`string`	no	The carrier’s SIP host (a name or an IP address).
`body.inbound_acl`	`string[]`	no
`body.inbound_assistant_id`	`string \| null`	no	`asst_…` ID.
`body.inbound_reserve_pct`	`integer`	no
`body.max_channels`	`integer`	no
`body.max_cps`	`integer`	no
`body.name`	`string`	no
`body.overflow_policy`	`"busy" \| "unavailable"`	no
`body.password`	`string \| null`	no	Write-only. A string sets it, null removes it; leave it out to keep the stored one.
`body.port`	`integer`	no
`body.register`	`boolean`	no
`body.register_expires_seconds`	`integer`	no
`body.transport`	`"udp"`	no
`body.type`	`"registration" \| "trunk"`	no
`body.username`	`string`	no
`options.headers["MoreVoice-Version"]`	`string`	no	The API version to use for this request. Defaults to the version the API key is pinned to.
`options`	`RequestOptions`	no	`idempotencyKey`, extra `headers` and an abort `signal`: see retries and idempotency.

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

import { createClient, createResources } from "@morevoice/sdk";

const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});

const connection = await mv.connections.update("conn_rtcFZ4v7Gg3mfomNppGQci", {
  max_cps: 10,
  password: "n3w-pa55",
});
console.log(connection);