Voice

SMS

FreeSwitch SIP Trunks
This guide provides a basic configuration of FreeSwitch to make inbound and outbound calls over the Wavix network. It gives a brief description of authentication options and SIP trunk redundancy.
Purchase a DID on the Wavix platform

Before placing or receiving a call, you need to have an active DID on your Wavix account. The steps below are optional if you already have an active number on your Wavix account.

To purchase a DID on your Wavix account:

1.

Log in to your account

2.

Click on Buy under Numbers & trunks in the top menu

3.

Select a country and region you wish to purchase a DID in

4.

Choose a specific number or numbers and click Buy now button

5.

You will be redirected to the Cart where you can confirm your choice and check out the DIDs

Fig. 1 Search and buy a number

Note

Some DIDs may require proof of local address and other documents before activation. You would need to upload the required documents and wait for the Wavix Provisioning team to approve them before the numbers become active.

Create a SIP Trunk on the Wavix platform
Fig. 2 Configure SIP trunk

To create a new SIP trunk on the Wavix platform:

1.

Select Trunks under Numbers & trunks in the top menu

2.

Click the Create new button

3.

Select Digest under the Authentication method

4.

Specify SIP trunk name, set SIP trunk password, and select one of the DIDs on your account as Caller ID

5.

Optionally you can set max outbound call duration, max number of simultaneous calls via the SIP trunk, and max call cost. If these parameters are not set, global account limits apply.

6.

Click Create

After the SIP trunk is successfully created, it will appear on the list of SIP trunks on your account.

Fig. 3 List of SIP trunks and SIP trunk ID

Important

Please be advised that your 5-digit SIP trunk username is generated automatically and displayed in the SIP trunk ID column

Basic SIP Trunk setup on FreeSwitch

For the purpose of this guide, we will use the following Wavix gateways:

  • Domain name: us.wavix.net; IP address: 209.58.144.243 as the primary gateway.
  • Domain name: nl.wavix.net; IP address: 95.211.82.14 as a secondary gateway

Note

Choose the primary and backup gateways that offer the lowest ping from your premises. The full list of the Wavix regional gateways can be found in the bottom of the page https://app.wavix.com/trunks.

Setting up outbound calls

To configure inbound and outbound calls on your FreeSwitch server:

1.

Navigate to /usr/local/FreeSwithc/conf/sip_profiles/external

2.

Create a new file wavix.xml

1
2
3
4
5
6
7
8
9
<include>
<gateway name="wavix">
<param name="username" value="YOUR_SIP_TRUNK_ID"/>
<param name="password" value="YOUR_SIP_TRUNK_PASSWORD"/>
<param name="realm" value="us.wavix.net"/>
<param name="register" value="true"/>
<param name="context" value="wavix"/>
</gateway>
</include>

Copy

Copy

Note

  • The authentication realm must match the domain name of the regional Wavix gateway you would routing your calls over
  • Enter the SIP trunk ID and password you configured for the SIP trunk on the Wavix platform in the “username” and “password” variables respectively

After you created the file, assign FreeSwitch user as the owner of this file so the FreeSwitch application can access it:

root@FreeSwitch:/usr/local/FreeSwitch/conf/sip_profiles/external/# chown FreeSwitch:FreeSwitch wavix.xml
3.

Navigate to /usr/local/FreeSwithc/conf/dialplan/

4.

Create a new dialplan wavix_dialplan.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<?xml version="1.0" encoding="UTF-8"?>
<include>
<context name="wavix">
<extension name="unloop">
<condition field="$${unroll_loops}" expression="^true$" />
<condition field="${sip_looped_call}" expression="^true$">
<action application="deflect" data="${destination_number}" />
</condition>
</extension>
<extension name="in-wavix">
<condition field="destination_number" expression="^(16468097065)$">
<action application="bridge" data="user/1000@$${domain}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="out-wavix">
<condition field="destination_number" expression="^(\d{10,15})$">
<action application="bridge" data="sofia/gateway/wavix/$1"/>
<action application="export" data="sip_from_uri=${sip_from_uri}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="local">
<condition field="destination_number" expression="^\d{4}$">
<action application="answer" />
<action application="sleep" data="1000" />
<action application="bridge" data="user/${destination_number}@$${domain}" />
<action application="hangup" />
</condition>
</extension>
</context>
</include>

Copy

Copy

After you created the file, give FreeSwitch access so it can read it.

Note

“expression="^(\d{10,15})$“- a regular expression matching dialed number. In this example, the rule will work if the dialed phone number contains 10 to 15 digits.

All destination phone numbers must be in the E.164 international format. E.164 numbers can have up to fifteen digits and are usually formatted as follows: [+][country code][subscriber number including area code]. An example of an US number in E.164 format is +16561223344. Calls to numbers without country code or carrying national access codes will be rejected by the Wavix platform.

Below are typical examples of incorrectly formatted phone numbers

Country
Number
Reason
Number in E.164 format

Country

US

Number

6561223344

Reason

No country code

Number in E.164 format

+16561223344

Country

UK

Number

020 1122 3344

Reason

No country code, national access code with leading 0

Number in E.164 format

+442011223344

Country

Switzerland

Number

0041797000777

Reason

Leading 00 international prefix

Number in E.164 format

+41797000777

Table 1 International E.164 phone number presentation

5.

Navigate to /usr/local/FreeSwitch/conf/directory/default/

6.

Modify extension configuration file 1000.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<include>
<user id="1000">
<params>
<param name="password" value="SET_EXTENSION_PASSWORD"/>
<param name="vm-password" value="1000"/>
</params>
<variables>
<variable name="toll_allow" value="domestic,international,local"/>
<variable name="accountcode" value="1000"/>
<variable name="user_context" value="wavix"/>
<variable name="effective_caller_id_name" value="CALLER_ID_NAME"/>
<variable name="effective_caller_id_number" value="16468097065"/>
<variable name="outbound_caller_id_name" value="$${outbound_caller_name}"/>
<variable name="outbound_caller_id_number" value="$${outbound_caller_id}"/>
<variable name="callgroup" value="support"/>
</variables>
</user>
</include>

Copy

Copy

Note

The value of the user_context variable <variable name="user_context" value="wavix"/> must match the name of the gateway configuration you created in the external SIP profile directory. The name should be without the file extension .xml.

7.

Navigate to /usr/local/FreeSwitch/conf/autoload_configs/default/

8.

Define RTP port range to 10000-20000 in the switch.conf.xml

1
2
<param name="rtp-start-port" value="10000"/>
<param name="rtp-end-port" value="20000"/>

Copy

Copy

9.

In order for FreeSwitch to reread the configuration files, the command fs_cli -x reloadxml should be executed.

Enable IP Authentication

Wavix will accept all calls originating from a particular IP address, without requiring any login info, when IP authentication is enabled. Note that you must have a dedicated IP for this option to work correctly.

Fig. 4 Wavix SIP trunk ID authentication

Follow the steps to enable IP Authentication on the Wavix platform:

1.

Select Trunks under Numbers & trunks in the top menu

2.

Click the More icon for the desired SIP trunk and click Edit

3.

Select IP Authentication under the Authentication method

4.

Put public IP address of your endpoint

5.

Click Submit

6.

Click Save to apply changes

Wavix support team will review your request and enable IP Authentication on the SIP trunk.

Note

  • When IP Authentication is enabled on a SIP trunk, it cannot be used as a destination for a DID. You must use a SIP URI instead
  • After submitting the IP authentication request, you’ll not be able to update your IP address or change the authentication method. By default, an IP address can only be mapped to a single SIP trunk. If you need to have several Wavix SIP trunks sharing the same IP address, please contact support@wavix.com

Once your request is approved by the Wavix support team, IP authentication will be activated on your Wavix SIP trunk, and you can configure it on the FreeSwitch:

1.

Navigate to /usr/local/FreeSwitch/conf/

2.

Update vars.xml file with the lines below

1
2
3
<X-PRE-PROCESS cmd="set" data="outbound-sip-ip=123.123.123.123"/>
<XPREPROCESS cmd="stun-set" data="external_rtp_ip=123.123.123.123"/>
<XPREPROCESS cmd="stun-set" data="external_sip_ip=123.123.123.123"/>

Copy

Copy

3.

Uncomment the lines for “ext-rtp-ip” and “ext-sip-ip” in the global configuration file external.xml and set them to reference the variables from vars.xml:

1
2
<param name="ext-rtp-ip" value="$${external_rtp_ip}"/>
<param name="ext-sip-ip" value="$${external_sip_ip}"/>

Copy

Copy

4.

Navigate to /usr/local/FreeSwithc/conf/sip_profiles/external/

5.

Create a new SIP profile wavix_ip.xml

1
2
3
4
5
6
7
8
9
<include>
<gateway name="wavix_ip">
<param name="proxy" value="us.wavix.net"/>
<param name="register" value="false"/>
<param name="context" value="wavix_gateway_ip"/>
<param name="retry-seconds" value="30"/>
<param name="expire-seconds" value="600"/>
</gateway>
</include>

Copy

Copy

6.

Add the following line to the dialplan:

<action application="set" data="sip_from_host=${outbound-sip-ip}"/>:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<?xml version="1.0" encoding="UTF-8"?>
<include>
<context name="wavix_ip">
<extension name="unloop">
<condition field="$${unroll_loops}" expression="^true$" />
<condition field="${sip_looped_call}" expression="^true$">
<action application="deflect" data="${destination_number}" />
</condition>
</extension>
<extension name="out-wavix_ip">
<condition field="destination_number" expression="^(\d{10,15})$">
<action application="set" data="sip_from_host=${outbound-sip-ip}"/>
<action application="bridge" data="sofia/gateway/wavix/$1"/>
<action application="export" data="sip_from_uri=${sip_from_uri}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="in-wavix">
<condition field="destination_number" expression="^(16468097065)$">
<action application="bridge" data="user/1000@$${domain}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="local">
<condition field="destination_number" expression="^\d{4}$">
<action application="answer" />
<action application="sleep" data="1000" />
<action application="bridge" data="user/${destination_number}@$${domain}" />
<action application="hangup" />
</condition>
</extension>
</context>
</include>

Copy

Copy

7.

Once you've created the file, assign FreeSwitch user as the owner of this file so the FreeSwitch application can access it:

root@FreeSwitch:/usr/local/FreeSwitch/conf/sip_profiles/external/ # chown FreeSwitch:FreeSwitch wavix_ip.xml

Configuration is completed and outbound calls should work now.

Placing Outbound calls with Caller ID Passthrough

Typically, you would use one of the DID numbers you purchased as the Caller ID for SIP trunk.

Fig. 5 Wavix SIP trunk Caller ID Passthough

Alternatively, you can enable Caller ID Passthrough option on the Wavix platform. It allows you to send your own A-numbers directly from FreeSwitch:

1.

Select Trunks under Numbers & trunks in the top menu

2.

Click on the three dots on the right hand side and select the Edit option

3.

Select Passthrough under the Caller ID

4.

Click Activate

5.

Click Save to apply changes

Wavix support team will review your request and enable Caller ID Passthrough on the SIP trunk.

Configure Custom Caller ID on FreeSwitch

Once your request is approved by the Wavix support team, the Caller ID Passthrough option will be activated on your Wavix SIP trunk and you can send your own Caller IDs from the FreeSwitch:

1.

Navigate to /usr/local/FreeSwithc/conf/sip_profiles/external/

2.

Update outbound SIP gateway configuration file wavix.xml

1
2
3
4
5
6
7
8
9
10
11
<include>
<gateway name="wavix">
<param name="username" value="SIP_TRUNK_ID"/>
<param name="password" value="SIP_TRUNK_PASSWORD"/>
<param name="realm" value="us.wavix.net"/>
<param name="register" value="true"/>
<param name="context" value="wavix"/>
<param name="caller-id-in-from" value="true"/>
<param name="sip_cid_type" value="none"/>
</gateway>
</include>

Copy

Copy

3.

Assign Caller ID to the variable "effective_caller_id_number" in the extension configuration file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<include>
<user id="1000">
<params>
<param name="password" value="SET_EXTENSION_PASSWORD"/>
<param name="vm-password" value="1000"/>
</params>
<variables>
<variable name="toll_allow" value="domestic,international,local"/>
<variable name="accountcode" value="1000"/>
<variable name="user_context" value="wavix"/>
<variable name="effective_caller_id_name" value="CALLER_ID_NAME"/>
<variable name="effective_caller_id_number" value="16468097065"/>
<variable name="outbound_caller_id_name" value="$${outbound_caller_name}"/>
<variable name="outbound_caller_id_number" value="$${outbound_caller_id}"/>
<variable name="callgroup" value="support"/>
</variables>
</user>
</include>

Copy

Copy

Setting up Inbound Calls

Registering SIP trunk

Registering your SIP trunk with one of the regional Wavix gateways is necessary (for digest authentication only) to receive inbound calls.

Register and send SIP traffic to regional gateways for low latency access. Read our FAQ.

Amsterdam, NL
nl.wavix.net
Dallas, USA
us.wavix.net
Singapore, SG
sg.wavix.net
Sydney, AU
au.wavix.net

Fig. 6 Wavix regional gateways

Select a regional gateway with the lowest latency to your device (in this example, it is us.wavix.net):

1.

Navigate to /usr/local/FreeSwithc/conf/sip_profiles/external/

2.

Create or update SIP external profile wavix.xml

1
2
3
4
5
6
7
8
9
10
11
<include>
<gateway name="wavix">
<param name="username" value="YOUR_SIP_TRUNK_ID"/>
<param name="password" value="YOUR_SIP_TRUNK_PASSWORD"/>
<param name="realm" value="us.wavix.net"/>
<param name="register" value="true"/>
<param name="context" value="wavix"/>
<param name="caller-id-in-from" value="true"/>
<param name="sip_cid_type" value="none"/>
</gateway>
</include>

Copy

Copy

Note

  • Each regional gateway has a unique authentication realm that corresponds to its domain name
  • Enter the SIP trunk ID and password you configured for the SIP trunk on the Wavix platform in the “username” and “password” variables respectively

You can check the status of your SIP trunk registration using the "fs_cli -x "sofia status gateway wavix" | grep State" command:

root@freeswitch:~# fs_cli -x “sofia status gateway wavix”
| grep State
PringState
0/0/0
State
REGED

Fig. 7 FreeSwitch SIP trunk registration status

If registration is successful, you will see ‘REGED’ in the “State” column. Please note that if the SIP gateway is not registered, incoming calls will not be routed to your FreeSwitch.

Fig. 8 Wavix DID configuration

Here is step by step configuring destination for inbound calls on the Wavix platform:

1.

Select My numbers under Numbers & trunk in the top menu

2.

Click on the three dots on the right-hand side and select the Edit number option.

3.

Select the destination trunk in the Destination section

4.

Click Add to add the destination for the DID

5.

Click Save to apply changes

Configuration is completed and inbound calls should work now.

SIP trunk redundancy

Considering SIP Trunk redundancy scenarios is important to ensure the continuity of business operations and protect against potential service interruptions. This guide provides configuration options to ensure redundancy for both incoming and outgoing calls.

Redundancy options for Inbound calls

In case of a regional gateway failure, Wavix may originate inbound call from any other gateway. You can find the full list of gateways in the bottom of the page https://app.wavix.com/trunks. There are two options available to prevent disruptions of inbound calls. You can set up SIP URI destination for DID number or enable dual SIP trunk registrations from the FreeSwitch. In this guide, we’ll use a SIP URI.

Fig. 9 Wavix DID configuration

To configure SIP URI destination on the Wavix platform:

1.

Select My numbers under Numbers & trunk in the top menu

2.

Click the three dots icon for the desired DID and click Edit number

3.

Select SIP URI under the Destination and enter URI in the format: DID@<Public IP of your endpoint>

4.

Click Add

5.

Click Save to apply changes

6.

Navigate to /usr/local/FreeSwitch/conf/dialplan/

7.

Specify your DID numbers in dialplan in <extension name="in-wavix"> extension

1
2
3
4
5
6
7
</extension>
<extension name="in-wavix">
<condition field="destination_number" expression="^(16468097065)$">
<action application="bridge" data="user/1000@$${domain}"/>
<action application="hangup"/>
</condition>
</extension>

Copy

Copy

Redundancy options for Outbound calls

1.

Navigate to /usr/local/FreeSwithc/conf/sip_profiles/external/

2.

Create a new file wavix_fo.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
<include>
<gateway name="wavix_fo">
<param name="username" value="YOUR_SIP_TRUNK_ID"/>
<param name="password" value="YOUR_SIP_TRUNK_PASSWORD"/>
<param name="proxy" value="nl.wavix.net"/>
<param name="expire-seconds" value="600"/>
<param name="register" value="true"/>
<param name="retry-seconds" value="30"/>
<param name="context" value="wavix"/>
<param name="caller-id-in-from" value="true"/>
<param name="sip_cid_type" value="none"/>
</gateway>
</include>

Copy

Copy

3.

Update the dialplan for outbound calls by adding the following lines:

1
2
<action application="set" data="continue_on_fail=true"/>
<action application="bridge" data="sofia/gateway/wavix_fo/$1"/>

Copy

Copy

See a dialplan example below

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?xml version="1.0" encoding="UTF-8"?>
<include>
<context name="wavix">
<extension name="unloop">
<condition field="$${unroll_loops}" expression="^true$" />
<condition field="${sip_looped_call}" expression="^true$">
<action application="deflect" data="${destination_number}" />
</condition>
</extension>
<extension name="in-wavix">
<condition field="destination_number" expression="^(16468097065)$">
<action application="bridge" data="user/1000@$${domain}"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="out-wavix">
<condition field="destination_number" expression="^(\d{10,15})$">
<action application="bridge" data="sofia/gateway/wavix/$1"/>
<action application="export" data="sip_from_uri=${sip_from_uri}"/>
<action application="set" data="continue_on_fail=true"/>
<action application="bridge" data="sofia/gateway/wavix_fo/$1"/>
<action application="hangup"/>
</condition>
</extension>
<extension name="local">
<condition field="destination_number" expression="^\d{4}$">
<action application="answer" />
<action application="sleep" data="1000" />
<action application="bridge" data="user/${destination_number}@$${domain}" />
<action application="hangup" />
</condition>
</extension>
</context>
</include>

Copy

Copy

Resolving typical problems

Typical problems with inbound calls

  • Make sure you have grant FreeSwitch access to the xml files you have created
  • Make sure that context name in dialplan, internal extension, and SIP profile extension are matching

Typical problems with outbound calls

  • 603 Declined response might be received when calling to the destination with the per minute rate higher than the Max call rate set for your account. You can find your effective Max call rate on the Trunks page. Please contact support@wavix.com to request a change to your Max call rate
  • Another possible reason for 603 Declined responses might be the lack of active registration. You can check registration status of the SIP trunk as outlined above.
  • Wrong destination number format. Make sure you dial the full international number (E.164): 19085594899 (US), 4408001218915 (UK). Dialing 9085594899 won't work. Strip prefixes like 0, 00 or 011 in front of the dialed number.

FreeSwitch SIP trunk diagnostics

  • Verify SIP trunk registration with ‘‘sofia status gateway <gateway-name>’ command in fs_cli command prompt. If registration is successful, you will see ‘REGED’ in the “State” column. Please note that if the SIP gateway is not registered, incoming calls will not be routed to your FreeSwitch.
  • In case you need to analyze SIP traffic, please use the sngrep tool with appropriate filters
Have a question?