SMSValve

Valve to send SMS using PhenixID Message Gateway .

Note: This valve is commonly used when sending notifications to users and administrators. NOT for sending one-time passwords.

Properties

Name Description Default value Mandatory Supports property expansion
gatewayURL URLs to PhenixID Message Gateways No No
recipient_param_name Parameter containing the recipient mobile number. mobile No Yes
userid_param_name Parameter containing the username. User-Name No Yes
wash_recipient_number If the mobile number should be cleaned from whitespaces and unwanted characters. true No No
use_flash If the text message should be sent as flash. true No No
recipient_prefix Prefixes the recipient number if it starts with '0'. (i.e. '+46') No No
force_prefix Always prefixes the recipient number. false No No
remove_leading_plus Removes leading '+'. false No No
recipients Static recipient numbers to receive the text. Added to the recipient picked up in the flow. No No
message_gateway_settings PhenixID Message Gateway Settings. Yes No
gw_username PhenixID Message Gateway username to override PhenixID Message Gateway Settings. No No
gw_password PhenixID Message Gateway password to override PhenixID Message Gateway Settings. No No
message SMS message content. Yes Yes
dynamic_values Dynamic template mapping values. Separated by pipe (|) Replaces key with value in the message sent to user.
Syntax: $$USERNAME={{item.givenName}}|$$SOME_OTHER_KEY={{item.somevalue}}
See example below.		 No Yes

Example Configuration 

{
        "name": "SMSValve",
        "config": { 
              "recipient_param_name":"{{item.othermobile}}",
              "userid_param_name":"{{request.username}}",
              "wash_recipient_number" : "true",
              "use_flash" : "false",
              "recipient_prefix" : "+46",
              "force_prefix" : "true",
              "recipients" : "+4655512345,+4655567890",
              "message_gateway_settings" : "ce4d2wer-css0-42ec-9800-129a6212",
              "message" : "Hello $$USERNAME, please check log file now.",
              "dynamic_values" : "$$USERNAME={{item.givenName}}"
        }
}

In the example above, the value for attribute othermobile has been picked up earlier in the flow.

The value for userid_param_name has been picked up from the request. Most common values are {{request.User-Name}} for RADIUS and {{request.username}} for HTTP.

Requirements

Item set must have at least one entry.

SMS request rate limiter

The rate at which SMS messages can be sent to any single recipient number is limited by the system, based on a moving average of the delay between consecutive requests. This functionality is characterised by four parameters, described below. 

Example, based on the default settings: a user that requests five SMS OTP:s, to the same number, within a period of 2.5 minutes will be quarantined for a period of 10 minutes, after which the limiter is reset and the user can start requesting SMS OTP:s again. 

The parameters are global and specified on the phenix-pipes module configuration, not on the valve configuration. Changes will affect all SMS valves.

Name
 Description
 Default value
request_interval_mean
 A lower bound for the moving average delay between consecutive requests, in seconds.
 30
request_lookback
 The number of recent requests that are used to calculate the moving average.
 5
request_quarantine_period
 If the average delay between requests in the lookback period drops below the lower bound, the recipient number will be quarantined for the period specified by this parameter, in seconds. After the quarantine period expires, the average delay calculation is reset.
 600
request_limiter_disabled
 Disables the limiter function.
 false