Script code

A script starts with the begin keyword and ends with the end keyword.

begin
  
  # route all messages to O2 UK SMSC 2
  SMSC = smscid("O2-SMSC-2")

end

Use the # character at the start of a line to include comments within a script.

SMSC assignment (SMSC =)

Sets an SMSC to where a message should be routed.

Specify the SMSC by its short name:

SMSC = smscid("MLSMSCSimX")

Specify the SMSC by its API ID:

SMSC = smscapiid("1387e426-c962-78fd-ac30-06666d5c3860")

Select the next SMSC from a group:

SMSC = smscgroup("MLSimulators1").rr

Complete message (`complete`)

Completes the message without submitting it to an SMSC, and generates a delivery receipt using the given message state and network error code.

complete status=5 error=123;
complete(5, 123);
complete(5);              # error defaults to 0

Parameter	Aliases	Description
`status`	`message_state`, `dlr_status`	SMPP `message_state` on the DLR (for example `2` delivered, `3` expired, `5` undeliverable)
`error`	`network_error`, `dlr_network_error`	Network error code on the DLR (defaults to `0`)

complete stops further execution of the script (similar to done) and finishes the message. The customer still receives a successful submit_sm_resp; completion is reflected in the subsequent DLR.

Example — treat STOP keywords as delivered without routing:

begin
match sm.short_message
  contains STOP { complete status=2 error=0; }
matchend
SMSC = smscid("DefaultSMSC")
end

match <field>

The match statement allows the comparison of <field> with values, where a match to a value will result in an action (typically an SMSC assignment or complete).

match sm.destination_addr  
  startswith 447711 { SMSC = smscid("BTC-SMSC1A"); done; } 
  startswith 447722 { SMSC = smscid("BTC-SMSC1B"); done; } 
matchend

The done keyword can be used to stop further execution of the script when a match takes place. Prefer done after an SMSC assignment when later arms or statements must not run. Prefer complete when the message should be finished rather than routed.

Match fields

<field> may be any of the following:

Field	Description	Example
SMPP account
`ac.system_id`	Account system ID sending the message. Alias: `system_id`	`match ac.system_id` / `abcd12340def { ... }` / `matchend`
`ac.system_type`	Account system type sending the message. Alias: `system_type`
Short message
`sm.service_type`	Service type field in the short message
`sm.source_addr`	Source address in the short message	`match sm.source_addr` / `447700123456 { ... }` / `matchend`
`sm.destination_addr`	Destination mobile number	`match sm.destination_addr` / `447700123456 { ... }` / `matchend`
`sm.destination_addr.country/dialcode`	Country dial code	`match sm.destination_addr.country/dialcode` / `44 { ... }` / `matchend`
`sm.destination_addr.country/iso3166`	Country two-letter ISO 3166-1 alpha-2 code	`match sm.destination_addr.country/iso3166` / `GB { ... }` / `matchend`
`sm.destination_addr.network/mnc`	Network MCC+MNC (for example `23415`)	`match sm.destination_addr.network/mnc` / `23415 { ... }` / `matchend`
`sm.short_message`	Short message text	`match sm.short_message` / `contains hello { ... }` / `matchend`
SMSC group cost
`sg.cost("...")/dialcode`	Submit cost for the named SMSC group for the message destination country (country default network)	see below
`sg.cost("...")/mnc`	Submit cost for the named SMSC group for the message destination network	see below

Data topics may also be used as fields using the form di.<topic_name> (numeric).

Cost field example

Compare the group's cost for the message's destination against a threshold:

match sg.cost("O2Bulk")/dialcode
  lt 0.05 { SMSC = smscgroup("O2Bulk").rr; done; }
matchend

Match values

The following comparison operators may be used with the value being compared:

Operator	Description	Example
`eq`	Equals (may be omitted)	`44 { ... }` or `eq 44 { ... }`
`neq`	Not equal
`startswith`	Starts with	`match sm.destination_addr` / `startswith 447700 { ... }` / `matchend`
`endswith`	Ends with
`contains`	Contains
`lt` or `<`	Less than (numeric)	`lt 0.05 { ... }`
`gt` or `>`	Greater than (numeric)
`lte` or `<=`	Less than or equal (numeric)
`gte` or `>=`	Greater than or equal (numeric)

if <expression>

Perform actions based on one or more criteria.

The fields used in criteria for match are supported in if statements, including typed fields (/dialcode, /iso3166, /mnc), data topics (di.*), and SMSC group costs.

if
  sm.destination_addr.country/dialcode eq 44 and
  sg.cost("O2Bulk").dialcode("44") < sg.cost("VFBulk").dialcode("44")
{ SMSC = smscid("O2SMSC-1A") }
else
{ SMSC = smscid("VFSMSC-1A") }

Cost operands in expressions use the form:

sg.cost("GroupName").dialcode("44") — cost for country dial code via that country's default network
sg.cost("GroupName").mnc("23415") — cost for MCC+MNC network

Combine clauses with and / or. Comparison operators: eq, neq, lt, gt, lte, gte, and <, >, <=, >=.

complete may be used inside if / else blocks:

begin
if sm.short_message contains STOP
{ complete status=2 error=0; }
else
{ SMSC = smscgroup("Default").rr; }
end