Sangoma PJSIP Configuration module for Asterisk
==============================================================================

This module provides an easy setup capability for Sangoma's Sangoma
SIP Trunking service.  Using only your Sangoma FreePBX Module Keycode
(or whichever Sangoma Trunking service), 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.

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 from
http://downloads.digium.com/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.

Configuration
-------------

The module's configuration is contained in /etc/asterisk/sangoma.conf.
The tarball download 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 = sipstation

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

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

"Could not retreive configuration for Sangoma object 'trunk1' using keycode
  '<a 64 character keycode string>': BADKEY"

  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.

"Could not retreive configuration for Sangoma object 'trunk1' using keycode
  '<a 64 character keycode string>': TEMPNOTAVAIL"

  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.
