Configure a SIP Trunk

A detailed guide to configuring a SIP trunk through the CarrierX Portal and programmatically.



Overview


SIP trunks enable you to send and receive calls via SIP. You will want to configure a SIP trunk if you have a current external application, office PBX, or wholesale carrier connection. When calls are made to the endpoint, the system will send them to the public IP address assigned to the endpoint.

This guide goes over creating an endpoint, configuring a trunk group, and assigning a phone number. It also goes over configuring the endpoint for placing and receiving calls.

SIP trunks can be configured through the Portal and programmatically.



Initial Setup Through the Portal



In this section, we will configure an endpoint through the Portal, and then assign a trunk group. A trunk group routes phone numbers to an endpoint. Note that a SIP trunk can also be configured programmatically, as is covered in a later section of this guide.

1. To set up a SIP trunk, log into your CarrierX account. On the left-side menu, locate and click on the Configure menu. Click Endpoints .



2. Click Add New Endpoint .



3. Enter a name for the new endpoint. This is a friendly name that is used for internal reference.



4. Check Provision Trunk Group to create a trunk group alongside the endpoint. A trunk group determines where a call should be routed. Trunks route calls to the appropriate endpoint by identifying the phone number dialed and matching it to the trunk group that the phone number is assigned to.



5. Select Third Party from the Select Endpoint Type dropdown menu.



6. Enter the public IP address of your SIP device. You can also add a port, otherwise it will default to 5060 . Note that you will also need to configure your firewall to accept the IP addresses listed on the System Gateway endpoint. The System Gateway endpoint is automatically created by the CarrierX system.



7. Click Create Endpoint .



Now that the SIP trunk has been configured, we can assign a phone number to this endpoint.

8. Navigate to the Configure menu and click Phone Numbers .



9. Click a phone number that you would like to associate with the endpoint trunk group. Alternatively, you can rent a new phone number. In this case, we will use a phone number that we have already rented.



10. Once you have selected a phone number, scroll down to see the phone number details. You will see a detail section like the following.



11. Click Edit .



12. Select the trunk group you would like to assign to the phone number.



13. Click Save .



Now your SIP trunk is configured and a phone number is associated with it.



Programmatically Configure a SIP Trunk



In this section, we will configure a SIP trunk programmatically using the CarrierX Core API.

1. Form a POST request with the field type and value third_party passed in the request body. You will also need to pass the field and value ip in the addresses array.

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type:application/json' \
--data-binary '{"addresses": [ { "ip": "124.93.122.43"} ], "type": "third_party" }' \
-u '[your_user_name]:[your_password]'


A successful request will return a 200 status code along with a response that looks like the following:

{
    "addresses": [
        {
            "direction": "any",
            "ip": "124.93.122.43",
            "port": 5060,
            "transport": "udp"
        }
    ],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "6a898445-62c1-46cf-be8b-25c2a3c87ec7",
    "name": "N/A",
    "partner_sid": "77354609-bd20-4ed0-a523-8c00792f15b8",
    "properties": {},
    "transformations": [],
    "type": "third_party",
    "voip_token": "7630d609-b0ae-41cf-bcc2-b326b5836370"
}


2. Form another POST request. This request will create a trunk group and assign it to the endpoint we just created. To create a trunk alongside the trunk group, pass the with_trunks field in the query URL with the value true . In the request body, pass the field name with a name for your new trunk group. Also pass a trunks array with the fields name and endpoint_sid .

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"New Trunk Group", "trunks":[{"name": "Trunk1", "endpoint_sid": "6a898445-62c1-46cf-be8b-25c2a3c87ec7"}]}' \
-u '[your_user_name]:[your_password]'


A successful request will return a 200 status code along with a response that looks like the following:

{
    "acls": [],
    "name": "New Trunk Group",
    "partner_sid": "77354609-bd20-4ed0-a523-8c00792f15b8",
    "routing_data": null,
    "routing_type": "failover",
    "soft_failure_codes": "408;",
    "soft_failure_cooldown": 120,
    "transformations": [],
    "trunk_group_sid": "31829e68-71ef-4e27-8f83-bb22ed67ae40",
    "trunks": [
        {
            "allow_forward": "disable",
            "call_type": "regular",
            "codec": null,
            "endpoint_sid": "6a898445-62c1-46cf-be8b-25c2a3c87ec7",
            "in_capacity": 0,
            "name": "Trunk1",
            "out_capacity": 0,
            "relay_sip_headers": [],
            "transformations": [],
            "trunk_sid": "af63f311-bad8-40bb-919d-eecb95affc1c"
        }
    ]
}


Now that we have programmatically created an endpoint and trunk group, we need to assign a phone number to the trunk group. Refer to the DID section of the Core API Reference Guide for information on renting and searching for DIDs.

3. Prior to renting a phone number, we need to find one that is available. For this, we will form a GET request and browse available DIDs.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1' \
-u '[your_user_name]:[your_password]'


A successful request will return a 200 status code along with a response that looks like the following:

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "capabilities": 7,
            "country_code": "USA",
            "did_group_sid": null,
            "did_sid": "c9Ua99icuPRvDvsikvlNaPzMLDXwuEYJ",
            "in_country_format": "(518) 777-8620",
            "international_format": "+1 518-777-8620",
            "locality": null,
            "name": "N/A",
            "partner_sid": null,
            "phonenumber": "15187778620",
            "price": "0.6",
            "state": "NY",
            "transformations": [],
            "trunk_group_sid": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1&offset=1"
    },
    "total": null
}


Take note of the field phonenumber , we will use the value in the next POST request.



4. Form a POST request. This request will assign a phone number that is available. The request will fail if the phone number is already rented. Pass the fields phonenumber and trunk_group_sid in the request body. The phonenumber value should be taken from the request above. The trunk_group_sid should correspond with the value of that field when we created the trunk group.

For a more comprehensive guide to renting a phone number, refer to the Rent a Phone Number Quick Start Guide.

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Content-Type: application/json' \
--data-binary '{"phonenumber":"15187778620", "trunk_group_sid":"31829e68-71ef-4e27-8f83-bb22ed67ae40"}' \
-u '[your_user_name]:[your_password]'


A successful request will return a 200 status code along with a response that looks like the following:

{
    "attributes": {},
    "callback_url": null,
    "capabilities": 7,
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "c9Ua99icuPRvDvsikvlNaPzMLDXwuEYJ",
    "in_country_format": "(518) 777-8620",
    "international_format": "+1 518-777-8620",
    "locality": null,
    "name": "N/A",
    "partner_sid": "77354609-bd20-4ed0-a523-8c00792f15b8",
    "phonenumber": "15187778620",
    "price": "0.6",
    "state": "NY",
    "transformations": [],
    "trunk_group_sid": "31829e68-71ef-4e27-8f83-bb22ed67ae40"
}


Configure a SIP Trunk to Receive Calls


In this section, we will learn how to configure a SIP trunk to receive calls.

1. You will need to set up your firewall to accept the IP addresses listed in your System Gateway endpoint. Note that this is a system generated endpoint that is automatically created for each account. To do this, navigate to the Configure menu and click Endpoints .



2. Click on the System Gateway endpoint.



3. Scroll down to see endpoint details. The IP addresses are listed in the Endpoint address attributes section.



Configure your firewall to accept traffic from these IP addresses. Now your endpoint is ready to receive calls.



Configure a SIP Trunk to Place Calls


In this section, we will learn how to configure a SIP trunk to place calls.

1. You will need to set up your firewall to accept the IP addresses listed in your System Gateway endpoint. Note that this is a system generated endpoint that is automaically created for each account. To do this, navigate to the Configure menu and click Endpoints .



2. Click on the endpoint titled System Gateway .



3. Scroll down to see endpoint details. The IP addresses are listed in the Endpoint address attributes section.



4. Configure your firewall to accept traffic from these IP addresses. Next, click on the third party endpoint we configured earlier.



5. Scroll down to see endpoint details. We use proxy authentication to place calls. For this, you will use the Endpoint SID as the username, and the VoIP Token as the password.



6. Click the Assigned Phone Numbers tab to view which phone numbers are associated with the endpoint. These are the phone numbers that calls can be made from.