How to Set Up and Manage Switchvox for the Switchvox Softphone

The Switchvox Softphone for Mobile is no longer actively supported.
Please see How to Set Up and Manage Switchvox for Sangoma Connect Mobile.

The Switchvox Softphone enables an iPhone or an Android phone to be used as a SIP phone with a Switchvox PBX. 

(This article is about Switchvox Softphone for Mobile. For information about the Switchvox Desktop Softphone for Windows and macOS, see How do I use the Switchvox Desktop Softphone App?)

​Switchvox Admins use the Switchvox Admin Suite (/admin) to add a Softphone Assignment to a phone extension, and to set correct networking parameters as required by the app. This document describes these Admin procedures.

See also: How do I use the Switchvox Softphone?

Requirements:

• Administrative Access to 

  • Setup > Manage Extensions

  • Setup > Phones > Digium Phones

  • Server > Networking

• Switchvox should be running the latest version of the Switchvox software. Mobile devices and their operating systems change on a regular basis, and the latest Switchvox software is required to handle those changes.

These are the network topologies that can be used with the Switchvox Softphone. 

• Switchvox in DMZ

• Switchvox is internal, with port forwarding and dual-resolve hostname. 

• Switchvox is internal, with port forwarding and NAT Reflection enabled.

NAT reflection is sometimes called NAT loopback, or NAT hairpinning. Without it, you must have a dual-resolve hostname for Switchvox. 

See What are the Differences among the Basic Network Topologies Used with the Switchvox Softphone for Mobile for illustrations of each topology.

Setting Network Parameters for the Switchvox Softphone 

Set the following Networking values:

Server > Networking > IP Configuration

• External IP address.  

• Allow NAT Port Forwarding set to YES.

• Advanced Options, Hostname. Set the hostname that resolves to Switchvox’s IP address. Depending on your chosen network topology and DNS entries, this hostname may resolve to Switchvox’s internal IP for a device that is on the local network and Switchvox's external IP for devices (e.g., the mobile softphone app) outside the local network.

• Advanced Options

  • Additional Local Networks should be used to list additional networks (such as a remote office VPN) connected to the local network. Networks can be listed in either CIDR or netmask notation.

  • Enable ICE Support should be set to YES. ICE enables a mobile softphone to communicate with Switchvox in the most efficient way possible.

Server > Networking > Access Control

• All Networks. Set the following entities to On:

  • SIP

  • User API

  • Web User Portal (optional, lets users configure the mobile softphone app via the email message)

Server > Networking > Phone Networks

Switchvox Softphone only uses the phone Network called All Networks. In the All Networks rule:

Direct Port Access is YES
Host Address must be as follows:

Firewall

It's important that your edge firewall passes data on the required ports. Please see Firewall/NAT Checklist.

Softphone Assignment Advanced Options

Some wireless carriers (e.g., Verizon) may not allow SIP traffic over standard port 5060 on their network. In this situation, you may need to turn on the following option:

Setup > Digium Phones > Softphones > Advanced Options

• Select YES for Alternate Configuration Port

Softphone Assignments for SIP Phone Extensions 

Switchvox Admins can assign SIP Phone extensions to phones. There are separate tabs for Desk Phones, Mobile Softphones, and Unassigned Extensions (extensions that don't have a phone). Open the following for Softphones:

Setup > Phones > Digium Phones > Mobile Softphones

Select the Unassigned Extensions tab to see who doesn’t have a phone, and assign either a desk phone or a softphone to a single extension. 

If you provide an email address that the user can access from their phone, that email message includes instructions and links for setting up the Switchvox Softphone. (If the Softphone Assignment is on an extension that is converged to a Main extension, then the email message will display the Main extension number and require the password to the Main extension number. The user can change the extension to the converged extension number, and use that password instead.)

The user can also download the app to their phone, and set up the app using the Switchvox Web Suite.

User (SIP Phone) Extensions

A Switchvox administrator can use the Manage Phones tool to set up one or more phone assignments for one person. In Setup > Manage Extensions, every user (SIP Phone) extension will have a Manage Phones action, where phone assignments and additional phone extensions and can be created and managed.

A Main phone extension that has a Mobile Softphone assignment, or has any additional phones with a Mobile Softphone assignment should have these settings in the Advanced Phone Options area:

• SIP Transport should be set to TCP. TLS/SRTP cannot be used, and UDP should not normally be used.

• ULAW or ALAW codecs should be allowed.

Consideration when using a VPN on your smartphone.

Technically there is nothing that prevents the software to connect to a PBX over a VPN if your organization requires you to use a VPN to connect to the internal services. 
Please read the following recommendations 

• If you use a route all traffic through VPN option in the VPN app, you do not have to open any ports outside the network (as described in the Firewall section). That option causes the device to look like it's inside the network to the PBX.

• Always use a hostname in your Phone Networks: All Networks item. Do not use an IP address.

• Server > IP Configuration > Additional Local Networks: include the CIDR block for the VPN.

• Depending on the smartphone's address on the VPN, you may need to modify Server > Access Control Rules. The same services will need to be On as if the smartphone were coming from outside of Switchvox's network. 

Understanding and troubleshooting Switchvox Mobile Softphone 

Switchvox mobile softphone behaves differently depending on the status of the application.  If the application and in the foreground, Switchvox Mobile softphone behaves just like a regular SIP-enable device, it will send SIP messages periodically to the PBX to update its registration and other SIP functions. You can confirm if SIP is ok, by loading the application and then the connection status page, in the phone tab. If you see an IP, most likely the connection is OK, if you don't see an IP, probably there is a networking issue or SIP ALG issue that may be preventing reliable SIP continuation.  If the application is closed or the background. Switchvox Mobile Softphone cease all communication with the PBX (including SIP), you can confirm by closing, and then check the PBX connection status page, in the phone tab;  You should see a green check however the IP address will be blank.

When the application is closed (or in the background), Switchvox Mobile Phone relays in the push notification system to wake up and receive calls.  PBX, upon receiving a call that is destined to a Switchvox Mobile device will send a push notification and then wait for the app to load and reports that is ready to receive the call. If you have a bad connection or your phone is behind a strict firewall, the notification may not reach the phone and thus, it won't be able to wake up to receive the call.

Another reason that your phone may not be able to receive calls may be related to a firewall rule that prevents access to Switchvox User API. When you load the application on your cell phone, the application registers its push notification token to the PBX using Switchvox API. If you would like to test the Switchvox API, you can enter the URL https://Ip.Of.The.PBX/xml, use the credentials of the extension when asked for the password, if you receive this message "Your request XML was empty." , it means that API interface is working. 

In summary, when troubleshooting Switchvox Mobile issues, please keep in mind the following points. 

• Switchvox Mobile Softphone uses the IP or Hostname that is set up in the Phone Networks -> All Network -> Primary Hostname (only), please make sure that is reachable from the network that your cell phone is located. 

• If you are using an FQDL as Hostname, please make sure that when you are inside of the internal network, your DNS resolves to the private IP address.  Most routers and firewalls will block connections from internal devices to internal servers via the internal server public address. 

• Switchvox Mobile Softphone as SIP-enabled device, it's susceptible to bad SIP ALG implementation, and many routers have this feature enabled by default (and some of them cannot allow to be disabled from its web interface). Use LTE Mode connection to test it. 

• If you are having trouble setting up the phone, try to enable alternative port (Setup -> Digium Phones -> Mobile Softphone -> Advanced Options) this setup the phone to use the alternative port to connect to the PBX, some providers blocks port UDP 5060.

• If you are having issues receiving calls, open the app (and keep it in the foreground) and then place a call,  if not successful, this can give you an indication that network may be preventing the connection (SIP ALG, Firewall rules, etc)

• If you are having issues receiving calls when the app is closed, confirm that the User API is open from the network where the phone is located (https://Ip.Of.The.PBX/xml), Please make sure to use the Hostname that is located in the Phone Networks -> All Network -> Primary Hostname

• Additionally, to confirm correct connectivity, you can open (keep it in the foreground)  the Switchvox Mobile Softphone and then go to your PBX -> Server -> Connection Status -> Phone and confirm if you see an IP, most likely the connection is OK.