Trunk Group Object

This section outlines the Trunk Group object.

Trunk Group Object Attributes

The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute	Data Type	Description
acls create update	array of objects	The Access Control Lists associated with the trunk group. Refer to the table below for more information.
external_handlers create update	array of objects	The list of the external handlers objects that will accept the requests and return a set of actions to perform. Refer to the table below for more information.
hard_failure_codes create update	string	The list of SIP codes on the basis of which the system defines the trunk failure, separated by `;`. If the number of reoccurence of such codes exceeds the `hard_failure_threshold` value within the period of time defined in the `hard_failure_interval`, the system will mark the trunk as "dead" until the end of the `hard_failure_cooldown` time. The default value is `408;`.
hard_failure_cooldown create update	integer	The cooldown interval the system waits before retrying to establish connection over a dead trunk, measured in seconds. The default value is `120`.
hard_failure_interval create update	integer	The interval during which the system checks the number of cause codes (`hard_failure_codes`), measured in seconds. The default value is `60`.
hard_failure_last_resort create update	string	This attribute specifies what the system must do in case of a hard failure of all the trunks in a trunk group. Possible values in this field are: if `first` set, then even if all the trunks in the trunk group are dead, the system will still try to establish connection over the first trunk. if `reject502` or `reject503` is set, then the corresponding the reject code will be returned in the case if no more trunks are available. The default value is `first`.
hard_failure_threshold create update	integer	The number of times the trunk can report the `hard_failure_codes` within the `hard_failure_interval` before it is considered "dead". The default value is `3`.
name create update	string	The trunk group name. If no value is passed at creation, the value assigned will be `N/A`.
partner read only	object	The Partner object associated with the trunk group. This field is displayed if `with_related` is set to `true` when performing the `GET` queries.
partner_sid create update	string	The secure ID of the partner associated with the trunk group.
routing_data create update	object	The additional routing data for trunks.
routing_type create update	string	The routing type for trunks. Values accepted in this field are `failover` and `round_robin`. For trunk groups with `routing_type` set to `failover`, CarrierX will attempt to call the trunk with the lowest `priority` value first. If the call fails, attempts will be made to call other trunks one by one in order of `priority`. For trunk groups with `routing_type` set to `round_robin`, the calls are sent to all the trunks, distributed among them according to their `weight` value. The default value is `failover`.
sip_options_locations create update	array	The list of `location_sid` values. The system will use these locations to monitor SIP options. If empty, the SIP options are disabled for all locations.
sip_options_threshold create update	integer	The number of SIP pings which must fail or succeed before the system marks the trunk "dead"/"alive". The default value is `3`.
soft_failure_codes create update	string	The SIP codes on the basis of which the system defines the trunk failure without marking it "dead", separated by `;`.
transformations create update	array of objects	The transformations associated with the trunk group. Refer to the transformations section for more information.
trunk_group_sid read only	string	The trunk group secure ID.
trunks read only	array of objects	The trunks of the trunk group. Refer to the Trunk object for more information.

Sample Trunk Group Object

{
    "acls": [],
    "hard_failure_codes": "408;",
    "hard_failure_cooldown": 120,
    "hard_failure_interval": 60,
    "hard_failure_last_resort": "first",
    "hard_failure_threshold": 3,
    "name": "New Trunk Group",
    "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
    "routing_data": null,
    "routing_type": "failover",
    "sip_options_locations": [],
    "sip_options_threshold": 3,
    "soft_failure_codes": "408;",
    "transformations": [],
    "trunk_group_sid": "503167ea-b8a5-4a5d-97e3-d684884da1d8",
    "trunks": [
        {
            "acls": [],
            "allow_forward": "disabled",
            "allow_transfer": false,
            "asn_mode": "disable",
            "call_type": "regular",
            "codec": null,
            "endpoint_sid": null,
            "in_capacity": 0,
            "in_identity_format": "passthrough",
            "in_identity_mode": "passthrough",
            "in_rfc_4694_mode": "cut_all",
            "location_sid": null,
            "name": "Trunk1",
            "out_capacity": 0,
            "out_identity_mode": "passthrough",
            "out_rfc_4694_mode": "cut_all",
            "priority": 0,
            "relay_sip_headers": [],
            "transformations": [],
            "trunk_sid": "fd97153a-e466-4de6-9484-c3d4dde72b85",
            "weight": 0
        }
    ]
}

ACL Object

Attribute	Data Type	Description
access_control_rules create update	array	The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules.
direction create update	string	The direction for the access control list. Values accepted in this field are: `any` to apply the rules from the list to both sent and received calls and messages. `inbound` to apply the rules from the list to received calls and messages. `outbound` to apply the rules from the list to sent calls and messages. `undirected` to apply the rules from the list to actions with no direction specified.
sms_action_false read only	string	For the Trunk Group Object this field is always `null` and `read-only` because Trunk Groups are used for voice only.
sms_action_true read only	string	For the Trunk Group Object this field is always `null` and `read-only` because Trunk Groups are used for voice only.
voice_action_false create update	string	The action to be executed for calls if no access control rules are applied. Values accepted in this field are: `accept` to accept the calls. `reject403` to reject the call with the `403` status code. `reject503` to reject the call with the `503` status code.
voice_action_true create update	string	The action to be executed for calls if any access control rules are applied. Values accepted in this field are: `accept` to accept the calls. `reject403` to reject the call with the `403` status code. `reject503` to reject the call with the `503` status code.

Trunk Group Handler Object

Attribute	Data Type	Description
direction create update	string	The direction of the call that will be processed by the external handlers. Values accepted in this field are: `any` for any call direction. `inbound` for the received calls. `outbound` for the sent calls.
error_handler create update	string	The action to be executed when the external handler returns an error or fails to respond within the specified timeout. Values accepted in this field are: `ignore` will ignore the error and continue to treat the call as if the handler did not exist. `reject403` will reject the call with the `403` status code. `reject503` will reject the call with the `503` status code. The default value is `ignore`.
timeout create update	integer	The maximum time for the external handler to respond in milliseconds. The default value is `250` (i.e., 250 milliseconds).
url create update	string	The external handler URL.

In the case the external_handlers list is not empty, when the call reaches this trunk group, a POST request will be made to the external handler URL (url) with the JSON containing SIP headers as its data. Refer to the table below for the detailed explanation of each SIP header.

Attribute	Description
Allow	The list of the supported SIP methods separated by commas.
Call-ID	A globally unique identifier for the call, which is a combination of a random string and the sender's host name or IP address separated by the `@` character.
Contact	Contains the SIP URI that can be used to contact the sender. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
Content-Length	The number of bytes in the message body.
Content-Type	Specifies the type of the SIP message content.
CSeq	The command sequence header that contains a sequence integer and the request name.
Date	The request date and time.
Diversion	Contains the information about the redirection of the call. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
From	Contains the information that identifies the sender of the message. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
Max-Forwards	An integer in the range of `0`-`255` that is used to indicate the maximum number of hops that a SIP request may take.
P-Charge-Info	A private SIP header, which passes an additional billing information about the party to be charged. This header is used between network entities for accurate billing of services. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
P-Charging-Vector	Is used to coordinate the charging records accumulated as the call is passed through different network entities.
Remote-Party-ID	Enables popular services as well as some regulatory and public safety requirements. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
Supported	Lists the option tags for the supported extensions. If empty, it means that no extensions are supported.
To	Identifies the receiver of the message. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
User-Agent	Is used to convey information about the user agent originating the request.
X-*	Custom headers used to specify additional information about the source originating the request (IP, UID, URI, etc.)

The external handler must be able to respond with a list of zero or more actions to perform. Refer to the sample below for more details on the actions accepted in the response.

Sample Handler POST Request

Sample JSON data of the POST request made to the external handler URL:

{
  "Allow" : [
    "INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY, INFO, PUBLISH, MESSAGE"
  ],
  "Call-ID" : [
    "243b35b872d5bb005af22dd9339e8149@10.1.10.190"
  ],
  "Contact" : [
    {
      "header_parameters" : {},
      "host" : "10.1.5.200:5060",
      "name" : "",
      "raw" : "<sip:15162065613@10.1.5.200:5060>",
      "uri_parameters" : {},
      "user" : "15162065613"
    }
  ],
  "Content-Length" : [
    "349"
  ],
  "Content-Type" : [
    "application/sdp"
  ],
  "CSeq" : [
    "103 INVITE"
  ],
  "Date" : [
    "Wed, 20 May 2020 08:46:17 GMT"
  ],
  "Diversion" : [
    {
      "header_parameters" : {
        "reason" : "unknown"
      },
      "host" : "null",
      "name" : "",
      "raw" : "<sip:19512623062@null>;reason=unknown",
      "uri_parameters" : {},
      "user" : "19512623062"
    }
  ],
  "From" : [
    {
      "header_parameters" : {
        "tag" : "as69da6efa"
      },
      "host" : "10.1.10.190",
      "name" : "IO",
      "raw" : "\"IO\" <sip:15162065613@10.1.10.190>;tag=as69da6efa",
      "uri_parameters" : {},
      "user" : "15162065613"
    }
  ],
  "Max-Forwards" : [
    "69"
  ],
  "P-Charge-Info" : [
    {
      "header_parameters" : {
        "cic" : "123",
        "noa" : "3",
        "npi" : "ISDN"
      },
      "host" : "162.251.180.230",
      "name" : "",
      "raw" : "<sip:+15174384314;cic=123@162.251.180.230;user=phone>;noa=3;npi=ISDN",
      "uri_parameters" : {
        "user" : "phone"
      },
      "user" : "+15174384314"
    }
  ],
  "P-Charging-Vector" : [
    "icid-value=ab5fc4ee59;icid-generated-at=12.7.193.171"
  ],
  "Remote-Party-ID" : [
    {
      "header_parameters" : {
        "screen" : "no",
        "privacy" : "off",
        "party" : "calling"
      },
      "host" : "10.1.10.190",
      "name" : "IO",
      "raw" : "\"IO\" <sip:15162065613@10.1.10.190>;party=calling;privacy=off;screen=no",
      "uri_parameters" : {},
      "user" : "15162065613"
    }
  ],
  "Supported" : [
    "replaces, timer"
  ],
  "To" : [
    {
      "header_parameters" : {},
      "host" : "10.1.10.190:5060",
      "name" : "",
      "raw" : "<sip:19512623062@10.1.10.190:5060>",
      "uri_parameters" : {},
      "user" : "19512623062"
    }
  ],
  "User-Agent" : [
    "VirtualPBX"
  ],
  "X-Src-IP" : [
    "10.1.5.200:5060"
  ],
  "X-Src-UID" : [
    "92d04fa7-f86f-4acd-a589-860569201845"
  ],
  "X-Src-URI" : [
    "19512623062"
  ]
}

External Handler Response

The external handlers support all the transformation actions available in CarrierX. The syntax also follows that of the transformations and includes the action and operands attributes of the selected transformation. The direction attribute is set in the Trunk Group Handler object.

[EXAMPLE]

For example, if the aim of the external handler is to reject the call, then this handler must respond with the reject value as an action, and one or more operands, which explain the reject reason. These reject reasons must be from the list of the available ones.

tip

Refer to the Using External Handlers quick start guide to learn more about how you can use external handlers to protect your calls.

Sample Handler Response

Sample external_handlers response with a reject action:

[
    {
        "action": "reject",
        "operands": ["forbidden", "aniblock"]
    }
]

This handler will return a Call-Info SIP header containing the message from the reject action:

Call-Info: "aniblock"