Voice Trunk

For the impatient

You may explore this data model via the API Playground, by clicking here

Endpoints

• /domains/{domain}/trunks[/{uuid}] (alias to /customers/self/domains/{domain}/trunks[/{uuid}])
• /customers/{customers}/domains/{domain}/trunks[/{uuid}]
• /trunks[/{uuid}] (alias to /customers/self/trunks)
• /customers/{customers}/trunks[/{uuid}] (access all trunks for all domains)

The Cloudonix trunk model represents an incoming or outgoing SIP connection to another telephony provider. Outbound trunk configurations can be used to send calls out from a Cloudonix domain - to the PSTN, a PBX or any SIP entity that can take calls, while inbound trunk configurations are used to match calls incoming into the Cloudonix border SIP gateways and route them into Cloudonix domains for DNID matching and voice application execution.

Properties

Property	Type	Editable	Description
uuid	String	no	The trunks unique identifier
name	String	Create, Update	A human readable name for the trunk.
ip	String	Create, Update	The IP address or host name that will either send calls or receive calls from Cloudonix (according to the direction field).
port	Number	Create, Update	The port to which Cloudonix will send calls, or receive calls from (according to the direction field).
transport	String	Create, Update	The IP transport protocol with which Cloudonix will send call to or receive calls on the trunk. Can be one of udp, tcp, or tls.
prefix	String	Create, Update	The "technical prefix" for that trunk. See below for a discussion of technical prefixes.
direction	String	Create, Update	Whether this trunk configuration is for an outbound trunk or an inbound trunk. Can be one of public-outbound, public-inbound, outbound, or inbound. See below for a discussion on the difference between "public" and "non-public" trunks.
profile	Object	Create, Update	A set of metadata fields that an application has assigned to this trunk configuration. Cloudonix recognizes and reads some specific properties, while the customer may also update the profile with whatever metadata they wish to store in Cloudonix.
active	Boolean	Update	Whether this trunk is available for routing calls.
metric	Number	No	Preference of routing through that this trunk - the higher the metric the less this trunk will be preferred for non-LCR specified routing. Set to -1 to have this trunk never considered for non-LCR routing.
domain	Object	No	The domain where calls to/from this trunk are handled.

Profile Properties

The following properties, if set on the profile field of the trunk configuration, will be recognized by Cloudonix and will cause the behavior documented below for that property. Additionally, for outbound trunks - when an outbound call is sent through that trunk - Cloudonix will add custom SIP headers for customer-specified properties in the trunk configuration's profile field in the format X-AP-{property-name}: {property-value}, if the property value is a string or a number.

Field	Type	Description
hostname	String	Force Cloudonix to route outbound calls on this outbound trunk only through a specific Cloudonix Border Gateway server. See below for a discussion on setting up the remote SIP termination peer and how the hostname setting affects that.
domain	String	Set the domain of the SIP INVITE message's "To" header to the specified value instead of the domain name of the Cloudonix domain that owns this trunk.
ruri-domain	String	Set the domain of the SIP INVITE message's Request URI to the specified value instead of the IP address of the trunk. The SIP connection will still be made to the trunk IP address.
connection-timeout	Number	Seconds to wait, in an outbound call, for the remote trunk to return a "progress" (ringing) or "answer" response, before trying the next trunk (or canceling). Default: 10.
provisional-timeout	Number	Seconds to wait, in an outbound call, for the remote trunk to return a provisional response, before trying the next trunk (or canceling). Default: 2.
authentication	Object	For outbound trunks, authenticatio details to use if the destination requires authentication, see below for details.

Technical Prefix Configuration

Cloudonix supports the use of "technical prefix" configuration to isolate traffic from multi-tenant SIP services.

For an outbound call, and if the outbound trunk configuration's direction field is set to public-outbound, Cloudonix will add the value of the prefix field from the outbound trunk configuration that is used for the call, in front of the destination specified by the voice application's Dial command.

For an inbound call, Cloudonix will only match the trunk configuration if the destination provided by the calling party starts with the value of the prefix field of the trunk configuration. Additionally, the matching inbound trunk configuration has its direction field set to public-inbound, Cloudonix will remove the matching prefix value from the start of the destination.

Inbound Trunk Limitations

Inbound trunk configurations must be globally unique (across the entire Cloudonix Platform) in their IP, port and prefix configuration, i.e. it is illegal to create two trunk configuration such that for an call incoming to the Cloudonix border gateway Cloudonix would not be able to identify the single matching trunk to handle that call, and the API.Core REST API will prevent such configurations from being created.

There is no such requirement for outbound trunks.

Far End Trunk Configuration

In addition to setting up the trunk configuration in Cloudonix, for SIP interconnect to work, it is important to set up the remote end of the trunk correctly in the SIP termination or DID provider. For each provider the domain needs to terminate to, or receive traffic from, a compatible trunk configuration should be set up in the non-Cloudonix system.

The following SIP parameters are often required in such a configuration:

• Remote IP Address or host name: Set to border.cloudonix.io. If the configuration does not allow a hostname, perform a DNS lookup for that name and use all of the resolved IP addresses. These IP addresses are not expected to change, and customers will receive a notification by email if any such change is planned.
• Remote Port: Set to 5060
• Transport Type or Protocol: Set to whatever you set the transport to in the Cloudonix trunk configuration.
• Technical Prefix (or often just "Prefix"): Set to whatever you set the prefix to in the Cloudonix trunk configuration.

As the Cloudonix Border Gateway is composed of multiple servers - for scalability and high availability - the recommended way to set up the trunk configuration in the SIP termination peer is to specify the Cloudonix Border Gateway's host name (border.cloudonix.io, as details above) as the sending address. For outbound trunks, sometimes the termination peer's SIP software does not support configuring the source of the traffic using host names, and possibly does not support specifying more than one IP address. In such a case it may be desired to select a single IP address (from the list of Cloudonix Border Gateway IP addresses), to be set as the source of traffic in the SIP termination peer's trunk configuration, and instruct Cloudonix to send all traffic on that trunk configuration - through that single border system. To do that, set the hostname property on the trunk configuration's profile to the selected Cloudonix Border Gateway IP address.

IP Addresses vs. FQDN

When specifying a host name (FQDN) instead of an IP address in a trunk configuration, is has sometimes not obvious effects that may be different than how a legacy SIP SBC or PBX system may handle such host names. There are different behaviors for outbound or inbound trunks, which are detailed below.

Outbound Trunks

For outbound trunks, if configured with a host name, the Cloudonix Border Gateway will use the global DNS system to resolve the hostname just before starting delivery of a call (i.e. after a voice application has invoked the command to dial out to the trunk). This has several effects:

• The time it takes to properly resolve the DNS address will delay the initial SIP connection, so it is important to make sure that DNS resolution of the hostname can be done in under 200ms, otherwise the user experience will be negatively affected.
• The host name must be resolvable at all times - if Cloudonix cannot resolve the host name - it will fail the call.
• If the hostname resolve to multiple addresses, either directly or through a CNAME reference, Cloudonix will use one address at random.
• The Cloudonix Border gateway, at this point, does not support SRV resolution.

Inbound Trunks

For inbound trunks, if configured with a hostname, the Cloudonix Border Gateway will attempt to match an incoming call by resolving the trunk host name and checking if any of the resolved IP addresses match the originator of the incoming call. This has several effects:

• The time it takes to properly resolve the DNS address will delay the activation of the Cloudonix voice application. During that time Cloudonix will not issue a SIP 180 or 183 status response, and therefor will send no ringing notification or early media, so it is important to make sure that DNS resolution of the hostname can be done in under 200ms, otherwise the user experience will be negatively affected.
• The host name must be resolvable at all times - if Cloudonix cannot resolve the host name - it will drop the call and will not return a failure message, as we treat calls that do not target a properly configured and active trunk as possible fraud attempt.

Outbound authentication

When sending calls to a SIP service provider that requires all calls to be authenticated using the SIP authorization scheme (RFC 3261 section 22), use the trunk profile field authentication to set the parameters for the SIP authentication. The value of the authentication field shall be an object with the following properties:

Field	Type	Description
username	String	The user name to use to authorize SIP requests.
password	String	The password for that user, that will be used to sign the authorized SIP request.
overwrite-from	boolean	When set, the SIP request will be forced to use the provided authentication user name as the caller ID. This is required by some SIP provider.