Sangoma Connect is a mobile client that supports Android and iOS mobile devices. The client is provisioned automatically based on a deep link URL, and access is granted to users entirely within the PBX User Management Module. The client maintains contact with the Sangoma Connect push servers and the PBX. Both the push servers and the Sangoma Connect client will register directly to the PBX using SIP registration via the public IP address of the PBX. When the client is active the registration will come directly from the mobile device. When the client is in standby, registration will come from a push server. It is necessary, therefore for the PBX to allow inbound SIP registrations from the internet, and also necessary for the extensions to support multiple active registrations.
PBX Version Requirement
Sangoma Connect is supported on PBXact and FreePBX versions 14 and later.
Asterisk Version Requirement
Any currently supported version of Asterisk (13,16,17) will work for audio calls, but Asterisk 16+ is required for video. If you are using DPMA you must upgrade the digium_phones rpm to current (yum upgrade and asterisk restart)
The Sangoma Connect mobile client uses PJSIP TCP signaling by default, but the default protocol can be configured with UDP, TCP and TLS. The selected transport must be enabled, and if behind a NAT router, there must be a route from the public IP to the selected PJSIP transport port. Any changes to bindings and transports in Settings, Asterisk SIP Settings requires an Asterisk restart after the Apply Config.
Sangoma Connect is only supported for User Management users whose primary linked extension is of type PJSIP. Now is the time to migrate users to PJSIP, and there are tools available to help you do that. If primary extensions are using chan_sip technology, you can still support Sangoma Connect by creating new user/extension pair and manually linking them to the existing chan_sip extension. See this section for more details.
When Sangoma Connect is enabled for a user linked to a PJSIP extension, the Sangoma Connect module automatically increments the extension's 'max contacts' parameter in order to allow multiple registrations to the same extension. It also sends the necessary client provisioning data to the client via the Sangoma Cloud which in turn allows the Sangoma Connect client to be provisioned with SIP credentials for registration.
Sangoma Connect mobile clients are provisioned by sending an email invitation to the user using the User Management module. The user receives the email on their mobile device and follows links to install and/or provision the mobile app. The email token will expire, so if the user does not act on the email promptly, they may need to request a new invitation. Each Sangoma Connect user MUST have a unique email address, multiple users can not share the same email address.
There is an alternate provisioning method if the mobile user is unable to receive an email. The PBX administrator can get the the deep link invitation URL from the admin GUI, and manually share the URL with the Sangoma Connect user. The user then loads the URL on their mobile device which then automatically provisions the Sangoma Connect client on the mobile device.
Sangoma Cloud Service
The Sangoma Cloud service acts as a proxy to facilitate non-SIP communications between the app and the PBX, to provision and authenticate the app as well as provide contacts and other data. The extension’s SIP credentials are not stored on Sangoma Cloud. All Sangoma Cloud servers are located in the U.S. and Canada, and are separate from the Sangoma Connect Push Notification servers.
Cloud Connect Agent
Once you install and enable the Sangoma Connect PBX module, the Connect Agent is deployed on your PBX server. This agent is required for communications between Sangoma Cloud and your PBX. In the unlikely event there is a failure in the installation of the Agent, you can again execute the command for installing and starting the Connect Module.
Endpoint Manager is not required for Sangoma Connect, but if you do have Endpoint Manager AND you have configured devices for use with PJSIP extensions, it's strongly recommended that you update the Endpoint Manager module to current. Older versions of Endpoint Manager have issues when changing the max contacts parameter on PJSIP extensions, which is required for Sangoma Connect operation. Proceeding with a legacy version of EPM is fine, but you first must back up your EPM extension mapping settings, delete the EPM mapping for the user/extension in question, enable Sangoma Connect for the user and then re-create (or re-import) the extension mapping again. Endpoint Manager versions 14.0.54 and 188.8.131.52 (or newer) resolve this issue completely and allow Sangoma Connect to be enabled seamlessly without any EPM changes.
LAN/WAN PBX IP
Sangoma Connect is provisioned to register only to a single FQDN (or IP) which can be set by the PBX administrator. Support for dual registration (i.e LAN/WAN or or auto failover) must be accomplished using DNS.
SIP registrations will come from
- The source IP of the device running the Sangoma Connect Mobile app (the user's mobile device).
- The Sangoma push notification servers.
Firewall Settings for Connect Mobile App Registrations
If using the PBX Firewall module for security, it is recommended that the Responsive option on the PBX Firewall module be enabled (for client registrations). This allows SIP registrations to your SIP transport from anywhere, as a mobile client's IP addresses will be unknown and change as the user moves around.
External firewalls must be similarly configured.
Firewall Settings for Sangoma Push Notification Server Registrations
When the Connect Mobile app goes to the background or closes, the client de-registers and a push notification registrar server is instructed to register to the PBX and listen for incoming SIP INVITEs. When a SIP INVITE is received, the push registrar server sends the notification to the Connect app, and the app is woken up/started by that notification. The Connect app then handles the communication between the user and PBX directly. The push notification servers store the SIP credentials for the purpose of registration, and those credentials are always transported and stored securely. The credentials are removed from the push servers when the app is reset or the Connect user is disabled on the PBX. Furthermore, the Push servers will stop attempting to register and remove the credentials if registration repeatedly fails. All push notification servers are located in the U.S., and are separate from the Sangoma Cloud servers.
In addition to the responsive firewall, the following IPs should be white listed both in the PBX Firewall (if in use) and in System Admin, Intrusion Detection. This ensures that none of the push notification servers will ever be blocked by your PBX.
External firewalls must be similarly configured.
This list of IPs is in addition to the responsive firewall used to protect against bad actors on other IP addresses.
The call media uses the RTP port range as defined in Asterisk SIP Settings, (default is 10000-20000).
Lack of call audio in either/both directions indicates either:
- Misconfiguration of the NAT settings.
- Lack of forwarding rule for the entire RTP range at the NAT router.
Changing SIP Credentials
If you change the SIP credentials for a user with an existing Sangoma Connect registration (PJSIP username and/or PJSIP secret) you will need to reprovision the Sangoma Connect Client. Browse to User Management and send a new email invitation to the user. The user will view the email on their mobile device and follow instructions to reprovision the client.
User Email Address
The Sangoma Connect client supports a single registration to a single PBX. Attempting to set up multiple accounts by using the same email address will reprovision the client with the latest registration details. The User Management user must have an email address configured, and the mobile device with the Sangoma Connect client installed must have the ability to receive email to that address. The email contains instructions to provision the client. Changing the User Management email address after the client has been provisioned requires a new email invite be sent from User Management.
PBX External Address
The Sangoma Connect client is provisioned to register only to a single IP/FQDN. You can use the default determined from the value set in Settings, Asterisk SIP Settings, External Address or define your own. At present, there is no client support for registering to multiple hosts (i.e. separate internal/external IPs).
The Sangoma Connect client is capable of video calls between local extensions. You must have a current version of Asterisk 16 (or higher) and you must ensure that 'Video Codecs' in Asterisk SIP Settings is enabled and that the h264 codec is listed. The allow/disallow fields on the Advanced tab of the individual extensions must not have a config that restricts usage of the h264 codec. It is conventional to leave the allow/disallow fields unpopulated so that the default codec selection in Asterisk SIP Settings is used for the extension(s).
SBC - Session Border Controller
Sangoma Connect supports direct registration using an FQDN, which can be set by the PBX administrator. If your PBX is behind an SBC or other SIP proxy on a different public IP, then the FQDN must resolve to the appropriate IP.
Workaround for chan_sip
There are two SIP drivers in Asterisk, the legacy chan_sip driver and the PJSIP driver. All new development is with PJSIP and chan_sip is deprecated. It is recommended that everyone update their systems such that they are only using PJSIP, but that is not always easy or even possible. Since Sangoma Connect only supports PJSIP extensions, this section provides a method by which legacy users can be supported by the Sangoma Connect mobile client. This method can also be used for cases where the primary extension is not SIP but some other tech such as DAHDI.
The work around involves leaving the existing extension and User Management user in place, and creating a new PJSIP extension and user. The new extension and user must then be manually configured to behave as if it's the same as the primary extension
The preferred and supported method for Sangoma Connect is to only use PJSIP. This method is intended as a work around for cases where it's not possible or not feasible to change extensions to PJSIP but where Sangoma Connect is still required. Not all PBX functionality is guaranteed with this method.
Steps to Set Up
Let us assume you have an existing chan_sip extension number 1100 and an existing User Management user with name 1100. You will not touch the settings on either of these except for Follow Me.
- Create a new dummy Extension and User. There are no requirements for the extension and user number/name, but it's conventional for the dummy to be the same as the primary with a prefix. In this case we'll create a pjsip extension and user of 881100
- Edit the new extension 881100 and click the 'advanced' tab. Locate the 'mailbox' field and change it to match the primary extension, in this case '1100@device'.
- On this same tab, locate the “CID Num Alias” field and change it to 1100 so that local calls from 881100 appear to come from the primary extension number.
- If voicemail was enabled as part of the create process, disable it now on the voicemail tab.
- On the General tab, Set Outbound CID and Emergency CID to match primary extension.
- Submit changes to extension 881100
- Browse to Applications, Follow Me and edit the primary extension, 1100
- Enable FMFM with a ring strategy of 'ringall' and a follow-me list that includes the primary extension and the dummy extension, 1100 and 881100. If you wish to add mobile numbers to this list, you can do so. Make the Destination if no answer be 'Follow Me - normal expected behavior'
- submit FMFM page
- Browse to Admin, User Management and edit the new user 881100
- Ensure that this user has an email address set correctly.
- Enable Sangoma Connect and submit
- Apply config
- Edit the user again and on the Sangoma Connect tab click the button to send invite.
You can now follow the directions for a normal Sangoma Connect install. The user should receive an email with Sangoma Connect client config instructions. Calls to extension 1100 should immediately ring both extension 1100 and the 881100 Sangoma Connect client. Calls from the Sangoma Connect client should appear to come from extension 1100. When dialing *97 or *98 from the Sangoma connect client, you will prompted to enter a mailbox number and pin, and from there check voicemail.
As noted above, this is not the preferred setup for Sangoma Connect. Calls made from Sangoma Connect will appear to come from the primary extension, but rules in place for things like Class of Service, Extension Routing must be updated to accommodate the new extension number. Things like Ring Groups and Queues need to be configured to either respect the FMFM settings or the new dummy extension must be added to them so the Sangoma Connect client will ring. Certain aspects of third party tools like XactView and iSymphony may not work at all since they make the assumption that the extension number dialing matches the Caller ID.