SMS Gateway Tasks

The SMS Gateway tasks allow outbound SMS capability from Patriot as an alternative to the GSM module. These tasks use an HTTP SMS gateway to send manual and automated SMS messages to cellular phones and other devices which support SMS.

There are a number of advantages over the GSM module, and is our recommended product for many enterprise scale customers.

Prerequisites

Supported SMS Gateway Providers

Installing the SMS Gateway Task

Patriot has many different SMS Gateway task variants:

All SMS Gateway task variants can be run on any machine running the Patriot Task Service. Ordinarily, the task should run on the primary Patriot server.

System Menu Item→Tasks → Task Settings

Please read TASK SETTINGS for general information about adding tasks.

add Add a new instance of your chosen SMS Gateway task variant by selecting it from the Task Type drop down list.

nextClick the next button to continue. The SMS Gateway task settings form will be displayed.

SMSGateway_taskSettingSMS Gateway task settings form - many settings are common between Patriot's various messaging tasks.

SMS Gateway Task Settings

Note: not all task settings will be available for every SMS Gateway task variant.

Enter a Description of the task, e.g. Clickatell SMS Gateway

The Task No. will default to the next free task number.

Select the Computer that this task is to be run on. This will default to the computer you are currently on. The chosen computer must have internet access.

Backup: Check this box if you wish this task to be defined as a backup task.

Text log Filter level can be use for task troubleshooting purposes. It should be left to the default None.

Enter a System Account No. The system account number is used to log any task errors and other system generated signals. The default is SMSG000101. If this account does not already exist you will need to set it up as a template under Maintenance -> Clients -> Templates, and import the System Generated Event Types.

Gateway Settings:

Gateway Server is the HTTP API address of the SMS Gateway. For Clickatell and SMS Global gateways always use the default value. HTTP/S port should be specified if different from the default 80/443 e.g. http://mgateserver:8100

User Name (Not required for SMS Gateway Platform) assigned to your online SMS Gateway account

Password (Not required for SMS Gateway Platform) assigned to your online SMS Gateway account

API Key (SMS Global, Clickatell Gateway Platform, and Emalify only) your API Key. Refer to the specific gateway provider sections for more information on API keys.

Secret (SMS Global and Emalify only) your API Secret Key. Refer to the SMS Global Gateway / Emalify sections for more information.

API ID (Clickatell Gateway only, not required for Clickatell Gateway Platform). Assigned to your online SMS Gateway account

Application Id (Emalify Gateway only). Your Emalify Project Id

Callback Enabled (Clickatell, SMS Global, and Emalify gateways only). Determines if the gateway provider should send final success/failure notifications when the message has been processed. See below for the additional setup required for this.

If Callback Enabled is turned on:

For Clickatell gateways Local IP Port No should be set to a free port on the Patriot Task Server Machine. This port must be configured to accept connections, and routed correctly from your external network firewall. Depending on your server setup, you may also need to add an HTTP Namespace Reservation on the selected port. SSL (HTTPS) is not supported directly - if your Clickatell account requires SSL then you will require a web server (e.g. IIS) with a trusted SSL certificate installed to terminate the SSL connection and offload to your Patriot task over HTTP.

For SMS Global and Emalify gateways Callback URL should be set to an HTTP URL which the gateway can use to HTTP postback to your Patriot Task Service. The URL (e.g. http://202.27.212.88:8201) should specify a TCP port which should be set to a free port on the Patriot Task Server Machine. This port must be configured to accept connections, and routed correctly from your external network firewall. Depending on your server setup, you may also need to add an HTTP Namespace Reservation on the selected port. Refer to the specific gateway provider sections for more information.

Use Unicode legacy Clickatell gateways only. Not required for the newer Clickatell SMS Gateway Platform. You must use Unicode if you need to send characters from outside the standard GSM set (essentially the Latin set). When using Unicode the effective character limit per message is halved. To compensate for this Patriot allows Unicode message concatenation (up to two messages) which gives a max Unicode message length of 140 characters. Be aware that your SMS gateway account will be charged for 2 messages when sending long Unicode messages (between 70 and 140 characters).

Gateway Provider (UFone and mGate gateways only). Select your gateway provider.

Sender ID (SMS Global, UFone, mGate, and Emalify gateways only). For UFone and mGate gateways this is the Sender ID for your gateway account. For SMS Global and Emalify gateways this is the number from where your SMS should appear to come from, and this number must first be registered to your gateway account.

Header Message is short text message prepended to all automated SMS messages

Number to Use specifies which user contact number to use when sending automated messages

Prefix is prepended to the destination number of all automated SMS messages - usually a country or area code

Attempts is the maximum number of times the system will attempt to send an SMS message if the first attempt is not successful. If all attempts fail, the system will wait the time specified in the Retry Wait field before trying again. This cycle will be repeated a maximum number times as set in the Retries field. Check the box to continue trying indefinitely.

Send Open/Close With Recent Alarm

Causes any set and unset signals received from a client to trigger automated messages to response members when received within a short period Within Time (Min) of an alarm event, the time can be set in System Wide Settings -> Data Service Settings -> Within Time(Min).

Note: for this option to work you must enable the system setting Send Open/Close With Recent Alarm in System Wide Settings and also enable this setting in SMS Gateway task settings.

Save Click Save to save task settings

SMS Global Gateway

This section applies to users of the SMS Global Gateway only.

Your company must have an account with SMS Global before you can operate this module with an SMS Global Gateway. Both outbound and inbound messaging are supported.

On the API & Integrations tab start by adding a new API Key for Patriot to use to access your account. Note down the Key and Secret fields which must be entered into the corresponding fields in the Patriot SMS Global task settings.

SMS Global API Key

Callback Notifications

SMS Global can notify you when outbound SMS messages are received (delivery receipts) as well as incoming messages or replies. To support this, a callback URL must be configured. The URL (e.g. http://202.27.212.88:8201) should specify a TCP port which should be set to a free port on the Patriot Task Server Machine. This port must be configured to accept connections, and routed correctly from your external network firewall. Depending on your server setup, you may also need to add an HTTP Namespace Reservation on the selected port. In your SMS Global Task settings in Patriot, select 'Callback Enabled' and enter the URL into the Callback URL field. To test that your Callback URL is accessible enter it into a web browser on a computer located outside of your LAN and confirm that a page containing the text "OK" is returned. If you have a dedicated number and want to support incoming messages that are not replies, you will need to enter the callback URL into your SMS Global account settings, as shown below.

Incoming Messages Support

Guardian Message Format

The SMS Global task can receive SMS messages from devices which support the Guardian message format. The Recv. Message Type setting must be set to Guardian.

Clickatell SMS Gateway

This section applies to users of the Clickatell SMS Gateways (including both the legacy "SMS Gateway" and the newer "SMS Gateway Platform").

Your company must have an account with Clickatell before you can operate this module with a Clickatell SMS Gateway. For Platform accounts setup a new SMS integration then follow steps to create an account. Please note two-way messaging is not supported. Once an account is created you change the environment to Production to start sending messages.

Clickatell requires international phone number formats for sending: + (Country Code) (Area Code) (Local number), such as +6421 555 1234 for an NZ mobile or +44 555 1234567 for the UK.

You can set up Clickatell to replace a leading zero with a particular country code, under the optional API settings:

Clickatell option for replacing leading zeros

Final Message Status Notifications

Once Patriot passes the message to the SMS Gateway, it is generally assumed to be successfully delivered. If you need notifications of failures to send from the SMS Gateway (e.g. the Gateway accepts the message but cannot deliver it), you need to enable message callbacks.

With callbacks enabled, the SMS Gateway will notify Patriot when the message has been successfully delivered, or provide details about any failures.

Setup

First, turn on Enable Callbacks and set the Local IP Port in the SMS Gateway task settings. Any free port can be used, however this port should be accessible by the SMS Gateway servers (port-forwarded from the external IP of the monitoring station).

Then enable delivery notifications in the Clickatell website settings. This must be done after the Patriot task is running.

Clickatell option for receiving notifications

Set the URL to the External IP address of your server followed by the Port number (follow the above example). The Method field can be set to either 'Http Get' or 'Http Post'.

Select 'Save Changes' to ensure your URL validates.

Telekom Slovenije SMS Gateway

This section applies to users of the Telekom Slovenije SMS Gateway only.

SmsSlovenijeTaskSettings
Telekom Slovenije Task Settings

Your company must contact Telekom Slovenije for your SMS gateway's certificate. The provided certificate must be installed on the task's machine. Ensure selected "Local Machine" as the Store Location and "Personal" as the Certificate Store.

The task also requires the certificate's thumbprint. Click here to read about how to retrieve the thumbprint of a certificate.

Twilio

Refer to Twilio module documentation.

Emalify

This section applies to users of the Emalify SMS gateway.

Emalify Account settings

Before setting up the Patriot task, you must configure your Emalify account settings in the Emalify Dashboard.

Begin by selecting the project you wish to use (or create a new project). Make a note of the Project Id.

Under Settings -> Api Services, ensure that the Bulk SMS service is activated. Then, under SMS -> Short Codes, make a note of the SenderName you want to use when sending messages from Patriot.

Next, view your User Profile, and check the API Credentials tab. Create a new App if required, and make a note of the Client ID and Client Secret values.

Emalify Patriot Task settings

Configure the Emalify task settings using the values noted from your Emalify account.

Delivery Report Callbacks

Once Patriot passes the message to Emalify, it is generally assumed to be successfully delivered. If you need notifications of failures to send from the SMS Gateway (e.g. Emalify accepts the message but cannot deliver it), you need to enable message callbacks.

With callbacks enabled, Emalify will notify Patriot when the message has been successfully delivered, or provide details about any failures.

To support this, a callback URL must be configured. The URL (e.g. http://202.27.212.88:8201) should specify a TCP port which should be set to a free port on the Patriot Task Server Machine. This port must be configured to accept connections, and routed correctly from your external network firewall. Depending on your server setup, you may also need to add an HTTP Namespace Reservation on the selected port. In your Emalify Task settings in Patriot, select 'Callback Enabled' and enter the URL into the Callback URL field.

Troubleshooting

SMS Gateway won't validate Callback URL:
Check the external firewall to ensure the port is correctly forwarded to the correct IP address. Also check if the port settings are correct in the windows firewall, keep in mind that the SMS Gateway task needs to be setup and running in Patriot for it to connect.
Access Denied error when starting task with Callback Enabled:
Add an HTTP Namespace Reservation for your Local IP Port.
Failed to listen because of conflicts with an existing registration:
The Local IP Port you have selected is being used already. Check other programs or select a different port for the task.