Configure SIP Trunking

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.

Definition

SIP Trunking refers to configuring and connecting your SIP server with CarrierX SIP services.

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

SIP trunking can be configured through the portal and programmatically.

How it works

Refer to our How It Works: Trunk Groups and Trunks section to learn more about what trunk groups and trunks are, what they are used for, and how you can work with them.

Configure Using the Portal

In this section, we will configure an endpoint and a trunk group, and then assign a phone number to that trunk group. A trunk group routes phone numbers to an endpoint.

note

Note that SIP trunking can also be configured programmatically, as is covered in a later section of this guide.

Endpoint Setup

To set up SIP trunking, log into your CarrierX account. First, create an endpoint. In the left-hand menu, go to CONFIGURE > Endpoints.

Click the Add New Endpoint button.

Enter a name for the new endpoint. This is a friendly name that is used for internal reference, e.g. My Third Party Endpoint.

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

Select the endpoint type from the corresponding dropdown menu. For the purposes of this tutorial, select Third Party.

Enter the public IP address of your SIP device. You can also add a port, otherwise it will default to 5060.

Click Create Endpoint.

note

Inside the trunk group we have just created by checking Provision Trunk Group, there will be just one trunk with the name N/A, which is created automatically at the trunk group creation. To find it, in the left-hand menu, go to CONFIGURE > Trunk Groups. In the list of Trunk Groups, click the one you need and when the trunk group details appear, scroll down to the bottom. Here you can edit or delete the existing trunks as well as add new ones. This SIP trunk is automatically associated with the endpoint we have created earlied.

Add a Phone Number

Now that we have configured a trunk group with a SIP trunk, we can assign a phone number we have rented earlier to this trunk group.

In the left-hand menu, navigate to CONFIGURE > Phone Numbers.

Click a phone number that you would like to associate with this 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.

Once you have selected a phone number, scroll down to see the phone number details. Click Edit.

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

Click Save.

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

Configure Using the REST API

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

Endpoint Creation

Form a POST request with the type set to third_party and the addresses field set with an array of ip addresses of you publicly accessible SIP application. You may also want to specify the port if your SIP application is running on any port dfferent from 5060. If no port is specied in the POST request, the default value of 5060 will be used. Optionally, you can also set a name for the endpoint, e.g. My Third Party Endpoint.

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type:application/json' \
--data-binary '{"addresses": [{"ip": "124.93.122.43", "port": "5060"}], "type": "third_party",  "name": "My Third Party Endpoint"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "addresses": [
        {
            "direction": "any",
            "dst_port": 5060,
            "ip": "124.93.122.43",
            "location_sid": null,
            "port": 5060,
            "priority": 0,
            "sip_password": null,
            "sip_username": null,
            "srtp": false,
            "transport": "udp"
        }
    ],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "6a898445-62c1-46cf-be8b-25c2a3c87ec7",
    "name": "My Third Party Endpoint",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "77354609-bd20-4ed0-a523-8c00792f15b8",
    "properties": {},
    "transformations": [],
    "type": "third_party",
    "voip_token": "7630d609-b0ae-41cf-bcc2-b326b5836370"
}

Endpoint SID

In the response to your request to create an endpoint, you will find endpoint_sid, in the above 6a898445-62c1-46cf-be8b-25c2a3c87ec7. Note the value in the response to your API call, as we will use it in the next step.

Trunk Group and Trunk Creation

Form another POST request. This request will create a trunk group with a trunk and assign that trunk to the endpoint we just created.

• To create a trunk alongside the trunk group, pass the query parameter with_trunks=true.
• In the request body, pass the fields:
  • name with a name for your new trunk group,
  • trunks, an array of objects with the name and endpoint_sid fields. The endpoint_sid is the value we noted in the step above.

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"}]}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "acls": [],
    "hard_failure_codes": "408;",
    "hard_failure_cooldown": 120,
    "hard_failure_interval": 60,
    "hard_failure_threshold": 3,
    "name": "New Trunk Group",
    "partner_sid": "77354609-bd20-4ed0-a523-8c00792f15b8",
    "routing_data": null,
    "routing_type": "failover",
    "sip_options_locations": [],
    "sip_options_threshold": 3,
    "soft_failure_codes": "408;",
    "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"
        }
     ]
}

Trunk Group SID

In the response to your request to create a trunk group, you will find trunk_group_sid, in the above 31829e68-71ef-4e27-8f83-bb22ed67ae40. Note the value in the response to your API call, as we will use it in the next step.

Phone Number Assignment

Now that we have programmatically created an endpoint and a trunk group, we need to assign a phone number to the trunk group.

API Reference

Refer to the Phone Numbers section of the Core API Reference for detailed information on renting and searching for DIDs.

In this tutorial, we will assign a phone number we have rented earlier to a trunk group by sending a PATCH request, which updates the phone number.

But first, let's select which phone number we would like to update. Send a GET request to see the list of phone numbers we have rented:

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 status code along with a JSON response that will contain the phone numbers we have rented earlier and their did_sid attribute. Select a phone number noting its did_sid.

Now form a PATCH request to update the phone number:

• Specify the phone number did_sid in the API URL. The did_sid value should be taken from the request above.
• In the body, set trunk_group_sid to the value we noted during the previous step.

curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/dids/f448e2c3-88c1-4cd1-8cf2-3567c16e0794' \
-H 'Content-Type: application/json' \
--data-binary '{"trunk_group_sid":"31829e68-71ef-4e27-8f83-bb22ed67ae40"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "active_capabilities": 4,
    "attributes": {},
    "callback_url": null,
    "capabilities": 31,
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "f448e2c3-88c1-4cd1-8cf2-3567c16e0794",
    "in_country_format": "(516) 206-5575",
    "international_format": "+1 516-206-5575",
    "locality": "NEW YORK",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065575",
    "price": "0.6",
    "state": "NY",
    "transformations": [],
    "trunk_group_sid": "31829e68-71ef-4e27-8f83-bb22ed67ae40"
}

Configure SIP Connections

In this section, we will learn how to configure SIP trunking to send and receive calls.

Configure Your Firewall

First, you will need to set up your firewall to accept the IP addresses listed in your System Gateway endpoint.

note

Note that System Gateway is a system-generated endpoint that is automatically created for each account.

To do this, in the left-hand menu, navigate to CONFIGURE > Endpoints.

Click the System Gateway endpoint.

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.

Authentication Setup

We use proxy authentication to send calls. For that purpose, you will use a username and a password that are available in My Third Party Endpoint we created earlier.

In the left-hand menu, navigate to CONFIGURE > Endpoints.

Click My Third Party Endpoint we have configured earlier.

Scroll down to see the endpoint details.

When placing calls, use the Endpoint SID as the username, and the VoIP Token as the password for proxy authentication.

Click the Assigned Phone Numbers tab to view which phone numbers are associated with the endpoint. These are the phone numbers you can use for sending and receiving calls.

Next Steps

You have configured SIP trunking! Now you can test incoming and outgoing calls on your new endpoint.

Refer to our Core API Reference for more in-depth documentation about Endpoints and Trunk Groups.