Sangoma PJSIP Configuration module for Asterisk
- Chris Maj
Overview
This module provides an easy setup capability for Sangoma's SIP Trunking services. Using only your Sangoma FreePBX Module Keycode (or whichever Sangoma Trunking service eg. retail SipStation or wholesale Sangoma Carrier Services (previously VoipInnovations)) this module retrieves configuration parameters, including your SIP credentials, from the Sangoma configuration servers and automatically configures PJSIP Endpoint, Authentication, AORs/Contact and Registration objects. Although the keycode is referred to as the "FreePBX Module Keycode" in the Sangoma portal, this module is intended for use in any standard Asterisk installation.
Launched onOct 31, 2024 this module is available for current Asterisk versions 20, 21 and 22.
Table of Contents
Installation
You can automatically download and install the res_pjsip_config_sangoma package by selecting it the “Resource Modules/External” section of Menuselect. When you subsequently run "make install", the package will be downloaded and installed.
You can also download the tarball package directly fromIndex of /pub/telephony/res_pjsip_config_sangoma/ Open the directory for your version of Asterisk and the appropriate 32 or 64 bit architecture, then choose the file for the “current” version.
Unpack the tarball and copy res_pjsip_config_sangoma.so to your Asterisk modules directory as specified by “astmoddir” in /etc/asterisk/asterisk.conf. Usually this is /usr/lib/asterisk/modules or /usr/lib64/asterisk/modules on most Redhat-based 64 bit distributions.
After copying, remember to check permissions, SELINUX ACLs, etc., to confirm the module is loadable by the asterisk process.
Configuration
The module's configuration is contained in /etc/asterisk/sangoma.conf. The tarball download (and the related documentation page here) has a fully documented sample file, but here's a minimum example:
; A name for your trunk. This will be used to create the PJSIP objects.
; In this example, your PJSIP Endpoint will be named "Sangoma1".
[Sangoma1]
; type must be "sangoma"
type = sangoma
; The FreePBX Module Keycode found in "My Services", "Trunk Groups" in the
; Sangoma Portal.
keycode = dfkjhsdgjhkasdjhgasdjhkduyrhafbcarbcsuhjcuayerncxndhjfnxzyreuniy
; At a minimum, you need to specify a dialplan context to receive incoming
; calls.
endpoint/context = trunk_inbound
; A provider must be specified. Current providers are sipstation and vi.
provider = sipstationAsterisk CLI Commands
Two new CLI commands have been added:
"pjsip export sangoma primitives" will dump the PJSIP configuration parameters for the endpoint, aor, auth and registration objects suitable for including in your pjsip.conf file directly.
"pjsip export sangoma wizard" will dump the PJSIP configuration parameters in a format suitable for use by the PJSIP Config Wizard.
If you do decide to use the output of those commands directly, make sure you disable this module to prevent duplicate objects from being registered.
SMS Support
This module provides a custom messaging technology, "sangoma", which can be used for sending SMS messages using your DIDs.
This message technology can be used by the MessageSend dialplan application as well as the ARI interface. The format of the URI for sending is "sangoma:target" where target is the phone number to send the SMS to. For example: "sangoma:15065551212". Note, however, that the from of the message must be one of your Sangoma DIDs. You can not send SMS messages from an arbitrary number.
You may need to comply with SIP campaign registry requirements for outbound text messages to the USA .
For incoming SMS messages these are delivered using a normal SIP MESSAGE request to your Asterisk. This will go into the dialplan at the configured message context using the message_context endpoint option or if none is configured then the value configured in the context endpoint option.
Using the following dialplan logic will improve the contents of the message by updating the To and From to contain the DID the SMS message was targeted to and the phone number that the message was received from:
[sangoma-in]
exten => s,1,Set(MESSAGE(from)=${PJSIP_PARSE_URI(${MESSAGE(from)},user)})
same => n,Set(MESSAGE(to)=${MESSAGE_DATA(X-sentto_did)})After this dialplan is executed you can direct the message accordingly depending on your needs.
There are some technicalities with SMS depending on which provider is used. SipStation expects incoming SMS on the 's' extension, while VI sends to an extension matching the number of the DID being sent to. The API VI uses is also strict with the leading 1 in the number. While it is possible to not include the 1 when sending SMS (it's taken care of behind the scenes), it DOES need to be specified for the incoming extension.
Common Issues
When Asterisk starts, this module will print several NOTICE messages indicating that the module is retrieving and processing the configuration received from the Sangoma configuration server. These are normal.
The most common errors you're likely to see are...
In this case, the keycode you typed is either invalid or not found. You should use Copy and Paste from the Sangoma portal to make sure you got it right.
This indicates that the keycode you're trying to use already has active registrations from an IP address other than the one you're trying from. If you're sure you do not have legitimate registrations from other IP addresses, you should contact Sangoma support immediately. If you require the capability to have multiple addresses registered temporarily, disable "Restrict Keycode Access" in the Sangoma portal but this should be used only as a temporary work-around.