Technical Details

Overview

Sangoma Talk 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 Talk push servers and the PBX. Both the push servers and the Sangoma Talk 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 Talk is supported on PBXact and FreePBX versions 14 and later.

Asterisk Version Requirement

Any currently supported version of Asterisk 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)

Signaling Requirement

The Sangoma Talk 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.

Extension Requirement

Sangoma Talk 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 Talk by creating new user/extension pair and manually linking them to the existing chan_sip extension. See this section for more details.

When Sangoma Talk 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 Talk client to be provisioned with SIP credentials for registration.

Email Invite

Sangoma Talk 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 Talk 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 Talk user. The user then loads the URL on their mobile device which then automatically provisions the Sangoma Talk 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 Talk Push Notification servers.

Cloud Connect Agent

Once you install and enable the Sangoma Connect PBX module, the Talk 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.

Domain Security

As a requirement of module install, an FQDN is automatically generated which maps to the IP of the PBX. The FQDN can be seen as the "Domain" when browsing to Module page in the PBX GUI, and follows the format [LongString].connect.sangoma.com. A malicious user could potentially use this FQDN to identify a specific IP as belonging to a PBX and tailor their targeting accordingly. As always, it's critically important to ensure that PBXs are secure, with the primary step being to enable and configure the PBX Firewall module.

Endpoint Manager

Endpoint Manager is not required for Sangoma Talk, 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 Talk 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 Talk for the user and then re-create (or re-import) the extension mapping again. Endpoint Manager versions 14.0.54 and 15.0.27.38 (or newer) resolve this issue completely and allow Sangoma Talk to be enabled seamlessly without any EPM changes.

LAN/WAN PBX IP

Sangoma Talk 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.

Firewall Settings

SIP registrations will come from

• The source IP of the device running the Sangoma Talk Mobile app (the user's mobile device).

• The Sangoma push notification servers.

• Misconfiguration of the NAT settings.

• Lack of forwarding rule for the entire RTP range at the NAT router.

Firewall Settings for Sangoma Talk Applications

Please ensure to whitelist “159.203.120.54” IP in your internal or external firewall in order to allow Talk applications like Visual Voicemails to work properly.

Changing SIP Credentials

If you change the SIP credentials for a user with an existing Sangoma Talk registration (PJSIP username and/or PJSIP secret) you will need to reprovision the Sangoma Talk 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 Talk 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 Talk 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 Talk 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).

Video Support

The Sangoma Talk 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 Talk 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.

Contacts

The contacts that are included in the Talk app include the PBX's internal extensions as seen in User Management. A user's globally recognized avatar from  Gravatar is automatically displayed. 

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 Talk only supports PJSIP extensions, this section provides a method by which legacy users can be supported by the Sangoma Talk 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 Talk 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 Talk is still required. Not all PBX functionality is guaranteed with this method.

1. 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.

   1. 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

   2. 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'.

   3. 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.

   4. If voicemail was enabled as part of the create process, disable it now on the voicemail tab.

   5. On the General tab, Set Outbound CID and Emergency CID to match primary extension.

   6. Submit changes to extension 881100

   7. Browse to Applications, Follow Me and edit the primary extension, 1100

   8. 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'

   9. submit FMFM page

   10. Browse to Admin, User Management and edit the new user 881100

   11. Ensure that this user has an email address set correctly. 

   12. Enable Sangoma Talk and submit

   13. Apply config

   14. Edit the user again and on the Sangoma Talk tab click the button to send invite.

Open