Configuring Hoiio SIP provider to work with FreePBX

This article shows you how to configure Hoiio, a popular Singapore-based VoIP provider, to work with FreePBX. For demonstration purposes, screenshots from FreePBX version 12 will be used, although most of the steps will be similar for earlier versions. You would also need a soft-phone such as X-Lite in order to test the configuration.

Prerequisites

To proceed with the setup guide, you should have already purchased a SIP account from www.hoiio.com and be provided with the following information:

1. SIP login username (e.g. sip6243674) – this is to authenticate your account with Hoiio
2. SIP account password
3. Incoming number (e.g. 65xxxxxxxx) – this is for you to receive incoming calls on your PBX

Adding Hoiio as a SIP trunk

First, login to your FreePBX management console, open the Administration module and select Trunks from the Connectivity menu:

Click on Add SIP (chan_sip) Trunk. In the resulting screen, enter a name for the SIP trunk and enter your Hoiio incoming number in the Outbound Caller ID field:

In the Outgoing Settings section, enter any name for the trunk name and provide the following information in the Peer Details text box:

host=siptrunk.hoiio.com
username=your_user_name
secret=xxx
type=peer

Replace your_user_name with your Hoiio SIP account username (e.g. sip6243674) and xxx with your Hoiio SIP account password. After that, in the Incoming Settings section, enter your Hoiio incoming number (e.g. 65xxxxxxxx) in the USER Context textbox, and type the following information in the USER Details textbox:

host=siptrunk.hoiio.com
type=peer
context=from-trunk
qualify=yes
insecure=invite

Finally, type the following information in the Register String field, replacing your_user_name with your Hoiio SIP account username (e.g. sip6243674) and xxx with your Hoiio SIP account password

your_user_name:xxx@siptrunk.hoiio.com

The final settings screen should look like below:

Click on Submit Changes to save the new SIP trunk.

Adding an outgoing route for Hoiio

Next, you need to tell FreePBX to terminate calls on the Hoiio account. To do this, select Outbound Routes from the Connectivity menu choose to add a new route:

Type a name for the route, enter a dial pattern which wil be used as a criteria to determine whether calls should be terminated via this router, and select Hoiio as the first trunk in the “Trunk Sequence for Matched Routes” section. Refer to this more information on the dial patterns configuration. For now, simply type 65XXXXXXXX in the “matched pattern” text field – this will tell FreePBX will terminate all calls to Singapore numbers via Hoiio. Save the new route settings when done.

Adding an inbound route

You will need to configure an inbound route in order to receive calls made to your Hoiio account incoming number on your PBX. If your Hoiio account does not come with an incoming number or if you do not wish to receive incoming calls, you may skip this section.

Select Outbound Routes from the Connectivity menu and choose to add a new route. Enter any name for the route and select a destination where incoming calls matching this route will be forwarded to in the Set Destination section. For simplicity, we simply select an existing extension to receive incoming calls. The rest of the settings can be kept as default.

The final outbound route settings should look like be

When you are done, click on Submit to save the route.

Adding extensions

You will need at least 1 extension on the PBX to test the configuration. Select Extensions from the Applications menu:

Choose to add a Generic CHAN SIP Device and click Submit. In the next screen, enter any name for the extension, and a number for the extension (e.g. 100). In the Secret field, type a password for the extension. Remove the pre-defined value from the Deny and Permit fields to allow everyone to authenticate using this extension. After that, choose to save the extensions.

At this point you are done with the configuration. Click Apply Config on the top right menu and wait a while for the changes to be applied:

Testing your configuration

Now start your softphone client and add a new SIP account with the following information:

• SIP server: IP address of your SIP server (e.g. 192.168.1.100)
• SIP username: the extension username as configured in the extension settings. Most likely, this is the extension number, e.g. 150
• SIP password: the extension password

First you need to test if your soft phone has successfully registered with the server. Its status should say “On Hook”, “Registered”, “Online” or similar.

Now try to make a call to a landline or mobile number from your soft phone (e.g. 656xxxxxxx or 659xxxxxxx) and see if you can talk to the other party. If yes, try calling your SIP account external number from your fixed line or mobile phone. If everything is fine, you should be able to answer the incoming call on your soft phone.

Congrats, you have successfully configured FreePBX to work with your Hoiio SIP account!

Troubleshooting

If for some reasons your test call does not work, this section lists some common issues and how to fix them.

Internal calls (e.g. calls to other extensions) are fine but calls to external numbers failed.
Most likely, there is an error in your FreePBX configuration that causes calls not to be terminated on the configured Hoiio SIP account. Open Outbound Routes from the Connectivity menu and check that there is at least one rule that terminates calls on the Hoiio account.

Outgoing calls seem to be made on Hoiio, but are either disconnected immediately or result in “invalid number” announcement
This is usually due to automatic adding of prefix to the number as a result of incorrect configuration.

• Check the Outbound Routes and make sure that the dial patterns are configured correctly
• Also check Connectivity>Trunks to make sure that the Hoiio SIP account configuration is correct

Some SIP clients may also have an option to automatically convert “+” to “00”. You should disable this, otherwise the wrong number may be called.

Incoming calls to the external number are disconnected immediately or forwarded to voice-mail despite the destination extension being available.
Check the following:

• Connectivity>Trunks: make sure that the Incoming Settings for the Hoiio SIP trunk is correct.
• Connectivity>Inbound Routes: make sure that there are no conflicting inbound routes blocking incoming calls on the Hoiio SIP account.

Additionally, some soft phones may have a do-not-disturb (DND) mode which will block incoming calls if enabled – check if this is the case. Asterisk also has a do-not-disturb mode for each extension that can be enabled by dialing *78 and disabled by dialing *79 from the extension phone. Refer to this post for more information.

Calls seems to be dropped at random half-way throughout the conversation
There could be a few reasons for this issue, most commonly intermittent network connections. However, if you still have the issue despite stable network connection, try to check the “Can Reinvite”, “Qualify” and “Qualify Frequency” settings of the extension that is having problem:

These settings are designed to ensure that the SIP client can maintain a stable connection with the server, but may cause issues if the network connection is bad or if the SIP client does not support the feature. Try to disabled these settings, re-register the extension and see if it helps.

Calls are made successfully but with no audio or only one-way audio
This is usually due to ports used for audio transmission being blocked by firewalls. SIP requires UDP port 5060 to be opened for data communication and UDP port 3478 for STUN server usage. Additionally a range of UDP ports are used for audio transmission, which need to be opened on the firewall too.

To find out which ports need to be open, check Settings > Asterisk SIP Settings:

Dial *43 (Echo Test) on the soft phone client and try to speak into the microphone. If configured properly, you should be able to hear yourself speaking, which indicates that there should be no problem with audio transmission when making calls.

Tips & tricks

The list of all extensions on the system and the default system extensions can be obtained from the Reports > Print Extensions menu.

Finally, the Reports > Asterisk Log Files menu provides direct access to the log files of Asterisk SIP server, which FreePBX is running on, for debugging purposes:

If you have direct access to the server, these log files are located at /var/log/asterisk. Refer to this article for more information.