Rules

Rules that can be applied to customer traffic

Rules can be created to perform actions on messages based on defined criteria. One or more rules can optionally be associated with a customer’s SMPP account and applied to each message they send (MT) or receive (MO).

Rules editor

Rules editor

When using the rules GUI, criteria can be graphically constructed and actions added in the required order. JSON is used to define rule actions (see Example rules).

Actions include:

  • reject message (return negative submit_sm_resp)

  • modify message

    • change parameter (TON, NPI, ESM class, registered delivery, randomise source address, etc)
    • change message content (replace, regex replace, insert text left/right)
  • routing (set SMSC to be used)

  • control message processing

    • selective use of content blocking lists

Criteria can be specified based on the fields in a submitted message (submit_sm), SMPP account parameters, the date/time and SMSC status.

Rules can also be applied to inbound (MO) SMS messages. Source address and destination address fields (including TON, NPI) can be used in criteria.

Types of rules (in order applied to messages):

  • Customer submit: Immediately applied to a customer’s messages when received by the SSG where the rule has been associated with the customer’s SMPP account under the Rules tab of their SMPP account.
  • Global routing: Applied to all outbound (MT) messages for an SSG instance and can be used to select the SMSC to which a message should be sent based on the rule’s criteria.
  • Global SMSC: Applied to messages after routing decision has been made and SMSC has been selected.

Read Example rules to see the criteria and actions for different uses.

Criteria


Criteria can be defined using SMPP account details and fields from submitted messages.

SMPP account

FieldMatch using
ac.system_idValue of fieldSMPP system ID
ac.system_typeValue of fieldSMPP system type

Routing

FieldMatch using
rt.is_smsc_selectedValue of fieldHas an SMSC been selected for routing message
rt.selected_smscValue of fieldSelected SMSC API ID

Short message (submit_sm) fields

FieldMatch using
sm.service_typeValue of fieldService type
sm.source_addrValue of fieldSource address
sm.destination_addrDigits of destination mobile numberDestination address
sm.destination_addr.countryCountry of destination mobile numberCountry of destination address
sm.destination_addr.networkNetwork of destination mobile number (based on mobile prefix)Network of destination address
sm.source_addr_tonValue of fieldTON of source address
sm.source_addr_tonValue of fieldNPI of source address
sm.dest_addr_tonValue of fieldTON of destination address
sm.dest_addr_tonValue of fieldNPI of destination address
sm.sm_default_msg_idValue of fieldDefault message ID
sm.protocol_idValue of fieldProtocol ID
sm.data_codingValue of fieldData coding
sm.esm_classValue of fieldESM class
sm.registered_deliveryValue of fieldRegistered delivery
sm.priority_flagValue of fieldPriority flag
sm.replace_if_present_flagValue of fieldReplace if present flag

Criteria operators

Criteria operators that can be used with parameters in a short message include:

eq - equal to
neq - not equal to
isnull - is equal to null
isnotnull - is not equal to null
lt - less than
lte - less than or equal to
gt - greater than
gte - greater than or equal to
startswith
doesnotstartwith
endswith
doesnotendwith
contains
doesnotcontain
isempty
isnotempty

Actions



Control: set SMSC connection priority queue

The priority_queue action is used to determine the priority of message routing to an SMSC connection. Messages are submitted based on the priority assigned: messages in higher-numbered priority queues are sent before those in lower-numbered queues. You can use any number to set the priority; a higher number indicates a higher priority.

Each SMSC connection can have multiple priority queues to control the order of message submission.

To set the priority for message submission to an SMSC connection, apply this action in conjunction with customer submit rules.

actionpriority_queue
controltype: number

Example priority queue numbers.

0 : no priority (default)
10 : low priority queue100 : medium priority queue
1000 : high priory queue
10000 : higher priority queue

Example: [{"action":"control", "priority_queue":100}]

Control: selective content blocking

Where content blocking lists have been applied to an account (Rules/Blocking tab of SMPP account), the use of these lists can be selectively applied to messages based on criteria.

The check_blocking_content action can be used to control if the blocking content list should be used or not. When a content blocking list is associated with an account, the short message will be checked against the list unless this action is used to not perform the check.

actioncheck_blocking_content
controltype: boolean

false: do not check message content against blocking content lists configured in SMPP account
true : check message content against blocking content lists configured in SMPP account and reject message if content found

Example: [{"action":"control", "check_blocking_content":true}]

Reject message

To immediately reject a message with a submit_sm_resp error when the customer submits it to the platform:

actionsubmit_sm_resp
rejecttype: number

Error number to be returned in SMPP command status field (default ESME_RSUBMITFAIL / 69 decimal).

Example: [{"action":"reject", "submit_sm_resp":69}]

To reject a message with a delivery receipt (DLR) after the customer has submitted it to the platform:

actiondlr_statusdlr_network_error
rejecttype: number

Message status to be returned in the DLR (e.g. 5 - "undeliverable"). See Delivery receipts.
type: number

Network error code to return in the DLR.

Example: [{"action":"reject", "dlr_status":5, "dlr_network_error":1}]

Modify message

General fields

Set field values.

actionparametervalue
modifysm.service_type
sm.source_addr
sm.destination_addr
type: string
sm.source_addr_ton
sm.source_addr_npi
sm.dest_addr_ton
sm_dest_addr_npi
sm.sm_default_msg_id
sm.protocol_id
sm.data_coding
sm.esm_class
sm.registered_delivery
sm.priority_flag
sm_replace_if_present_flag
type: number

Example: [{"action":"modify", "parameter":"sm.source_addr", "value":"Google"}]

Modify source address field - trim left

Trim the specified number of digits from the start of the source address field value.

actionparameteropdigits
modifysm.source_addrtrimlefttype: number Number of digits to trim from start of address.

Example: [{"action":"modify", "parameter":"sm.source_addr", "op":"trimleft", "digits":2}]

Modify source address field - random digits

Set source address field value to begin with prefix digits and followed by specified number of random digits.

actionparameteropprefixdigits
modifysm.source_addrrandomtype: string Digits at start of source address.type: number Number of random digits to append to prefix.

Example: [{"action":"modify", "parameter":"sm.source_addr", "op":"random", "prefix":"447700", "digits":6}]

Modify destination address field - regular expression replace

actionparameteroprefmt
modifysm.destination_addrregex_replace

Regular expression replacement of digits.
type: string

ECMAScript regular expression

Example: 447968
type: string

Example: 447944

Example: [{"action":"modify", "parameter":"sm.short_message", "op":"regex_replace", "re":"447968", "fmt":"447944"}]

Using re of 447968 and fmt of 447944, an sm.destination_addr field with “447968847040” will be replaced with “447944847040“.

Modify short message field - assign, insert

actionparameteropvalue
modifysm.short_messageassign

Replace short message text with value specified.

insert_left

Insert at start of short message the value specified.

insert_right

Insert at end of short message the value specified.
type: string

Text for short message field.

Modify short message field - regular expression replace

Supports UCS2 and non-UCS2 data codings. Result data coding is the same as input data coding. Replace operation must therefore not introduce character that input data coding does not support.

actionparameteroprefmt
modifysm.short_messageregex_replace

Regular expression replacement of text.
type: string

ECMAScript regular expression

Example: a|e|i|o|u
type: string

Example: [$&]

Example: [{"action":"modify", "parameter":"sm.short_message", "op":"regex_replace", "re":"a|e|i|o|u", "fmt":"[$&]"}]

Using re of a|e|i|o|u and fmt of [$&], an sm.short_message field with “Quick brown fox” will be replaced with “Q[u][i]ck br[o]wn f[o]x“.

Further examples for regex_replace

Inputregex_replaceOutput
Hello Petra. 1232 è il tuo codice di verifica.re: ^(.+)\s(\d_)\s.+

fmt: PIN code: $2. Please keep this safe.

Action:[{"action":"modify", "parameter":"sm.short_message", "op":"regex_replace", "re":"^(.+)\\s(\\d_)\\s.+", "fmt":"PIN code: $2. Please keep this safe."}]
PIN code: 1232. Please keep this safe.

Set SMSC route (global routing rule)

actionsmsc
routetype: string
SMSC API ID of the SMSC to which the message should be routed. This ID can be found under the Control tab of the SMSC’s configuration dialog.

Example: [{"action":"route", "smsc":"131234b8-aaaa-11eb-abcd-0123455c3860"}]

Resources

Useful resource for regular expression testing: https://regex101.com