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.
- No physical hardware is required
- World-wide SMS coverage via the Clickatell or SMS Global gateway providers, and others.
- High volume SMS capability
Prerequisites
- At least one of the Patriot SMS modules must be registered (see below).
- An active account with a supported external SMS Gateway Provider.
- The Patriot Server running the instance of the Task Service hosting the SMS Gateway Task must have internet access to the HTTP SMS Gateway.
- If the gate way is from Telekom Slovenije, a SSL certificate from Telekom Slovenije needed to be installed. More on this on later section.
Supported SMS Gateway Providers
- Clickatell (requires SMS Gateway module)
- UFone Business SMS (requires SMS Gateway module)
- mGate Digital SMS (requires SMS Gateway module)
- SMS Global (requires SMS Global module)
- Telekom Slovenije (requires SMS Telecom Slovenije module)
- Twilio (requires Twilio module)
- Emalify (requires Emalify module)
- Various regional providers emulating one of the above services
Installing the SMS Gateway Task
Patriot has many different SMS Gateway task variants:
- SMS Gateway (Platform) use this for Clickatell accounts created November 2016 onwards.
- SMS Gateway use this for Clickatell accounts created prior to November 2016
- Generic SMS Gateway use this for all UFone and mGate accounts. Set the Gateway Provider task setting to either UFone or mGate.
- SMS Global use this for all SMS Global accounts.
- SMS Telecom Slovenije use this for Telekom Slovenije
- Twilio use this with your Twilio account.
Patriot supports WhatsApp and Facebook Messenger messages in addition to SMS via this gateway. Only automated messages generated from a pre-approved message format are supported.
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 a new instance of your chosen SMS Gateway task variant by selecting it from the Task Type drop down list.
Click the next button to continue. The SMS Gateway task settings form will be displayed.
- SMS Gateway
- SMS Global
- Emalify
SMS Gateway Task Settings
Many settings are common between Patriot's various messaging tasks and 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). If enabled the task will listen for HTTP notifications back from the SMS Gateway server. This is required to receive inbound messages (currently SMS Global only) and delivery receipts. 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://123.45.67.89:1234) 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.
Require Delivery Receipts (Clickatell, SMS Global and Emalify gateways only). If enabled the task will require a final delivery success notification back from the gateway server within the Message Timeout before logging a message as a successful send. This option is only available when Callback Enabled is checked. Beware that SMS gateway services typically do not guarantee that delivery receipts will be received for all destinations as they may not always be supported by the destination network. Also beware if you enable this option and a delivery receipt is not received within the Retry Wait time then the message may be resent which may result in the duplicate messages eventually being received by the destination.
Combine Long Messages (SMS Global only) This will check if a message is part of a long message and combine them. Without this setting all messages received will be interpreted as individual messages.
Long Messages Timeout (SMS Global only) requires Combine Long Messages. This is the minimum wait time (seconds) for receiving multiple parts of a message. Default to 10 seconds, maximum wait time allowed is 10 minutes (600 seconds). If any parts of the message have not arrived by the end of the timeout period then all parts of this message will be treated as individual messages.
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).
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.
Recv. Message Type (SMS Global Only)
The SMS Global task supports a few different received message formats. These can be used by mobile users and devices to acknowledge alarms, or to report alarm and location data.
In addition to the Standard Received Message Types, SMS Global supports the following received message types:
- Guardian- Receive alarm & location SMS from Guardian devices.
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.
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://123.45.67.89:1234) 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.
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:
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.
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.
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.
- Application Id - your Emalify Project Id
- Api Key - your Emalify credentials Client Id
- Secret - your Emalify credentials Client Secret
- Sender Id - your Emalify Short Code SenderName
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://123.45.67.89:1234) 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.