Configuring Hoiio SIP provider to work with FreePBX

0.00 avg. rating (0% score) - 0 votes

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.


To proceed with the setup guide, you should have already purchased a SIP account from 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:

Connectivity - Trunks

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:

trunk details

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

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:

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

The final settings screen should look like below:

trunk details 2

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:

Connectivity - Outbound Routes

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

Connectivity - Inbound Routes

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:

Application - Extensions

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.
  • 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!


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:

ext pwd & qualify

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:

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:

Reports - Asterisk Logfiles

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

0.00 avg. rating (0% score) - 0 votes


A tough developer who likes to work on just about anything, from software development to electronics, and share his knowledge with the rest of the world.

One thought on “Configuring Hoiio SIP provider to work with FreePBX

  • September 16, 2015 at 4:19 pm

    This is very helpful. Thanks tons MD!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>