Dynamic SMS Message Routing with HTTP Callbacks

If you need control over routing to particular SMSC connections, the logic that NowSMS uses for SMS message routing is described in detail in the following article: http://blog.nowsms.com/2008/07/routing-sms-messages-to-specifc-smsc.html

For some installations, the routing control offered by NowSMS does not provide enough control.

For these installations, an HTTP based callback exists which allows an external application to specify the desired SMS message routing. This callback exists only in NowSMS 2009 and later releases. NowSMS 2009 is currently available as a release candidate via the download link http://www.nowsms.com/download/nowsms2009.zip.

The SMS message routing callback is an extension of the existing SMS accounting callbacks, which are described in the following article: http://www.nowsms.com/support/bulletins/tb-nowsms-001.htm

In NowSMS 2009 and later releases, the "SMS Send Accounting Callback" has been extended so that the response to the callback can include routing information for the SMS message.

The SMS Accouting callback URL is defined in the SMSGW.INI file, under the [SMSGW] section header:

SMSAccountingURL=http://server.name/path

The variables listed in the sections below will be added to the SMSAccountingURL when the URL is executed by the gateway as HTTP GET (CGI-style) parameters.

SMSSend PreAuth Callback

This callback is executed when an SMS (web, SMPP, SMTP) user is requesting to send a message.

This is a “pre-authorisation” request, and does not mean that the message will actually be accepted by NowSMS for delivery. If NowSMS cannot successfully connect to the accounting URL, or the URL returns a response other than a standard “HTTP 200 OK” response, the user request to send a message will be blocked. A “PreAuth” request to send a message will also be blocked if the response includes the text “PreAuth=Deny”.

The following variables will be set for a pre-authorisation request:

PreAuth=Yes (indicates that the message is a Pre-Authorisation Request)
Type=SMSSend
From=Defined "SMS Users" Account
To=Comma delimited list of message recipients (will not be present if message is addressed to more than 100 recipients)
MsgCount=#### (number of recipients user is requesting to send the message to)
SubmitIP=a.b.c.d
SMSCRoute=xxxxxx (optional, will be present only if an explicit route was requested in message submission)
Sender=xxxxxx (optional, will be present only if a sender address was specified in message submission)
Binary=1 (optional, will be present if the message is binary)
PID=# (optional, will be present only if a non-zero PID value was specified in message submission)
DCS=# (optional, will be present only if a non-zero DCS value was specified in message submission)
UDH=HexString (optional, will be present only if message contains User Data Header)
Data=HexString (optional, will be present only if message is binary)
Text=String (optional, will be present only if message is text)
ReceiptRequested=Yes (optional, will be present only if message is requesting a delivery receipt ... only available in v2009.01.26 and later)

(Note: For SMTP message submissions, only PreAuth, Type, From, To and MsgCount variables will be present.)

Example:

http://server.name/path?PreAuth=Yes&Type=SMSSend&From=UserAccount&To=%2B447777777777&MsgCount=1&SubmitIP=127.0.0.1&Text=This%20is%20a%20test.

Note that URL escaping is performed when building the URL string. Most HTTP scripting languages will automatically unescape these parameters for you (e.g., %2B is translated back to "+" and %20 is translated back to a space character).


SMSSend Accounting Callback

This callback is executed after an SMS message that has been sent by an SMS user has been accepted by the gateway for delivery.

In NowSMS 2009 and later, NowSMS will check the response to the HTTP request. If this response includes the text "SMSCRoute=xxxxx", then NowSMS will apply this SMSC route for the message. The specified route "xxxxx" can either be the name of a particular SMSC connection (e.g., "SMPP - host:port"), or it can be the value of the "RouteName=" attribute defined for one or more connections. (For more information on the "RouteName=" attribute, see http://blog.nowsms.com/2008/07/routing-sms-messages-to-specifc-smsc.html.)

The following variables will be set for the accounting callback:

Type=SMSSend
From=Defined "SMS Users" Account
To=Message Recipient Phone Number (if the message is sent to multiple recipients, this callback is repeated for each recipient)
MessageID=Message ID assigned to the message by NowSMS
SubmitIP=a.b.c.d
SMSCRoute=xxxxxx (optional, will be present only if an explicit route was requested in message submission)
Sender=xxxxxx (optional, will be present only if a sender address was specified in message submission)
Binary=1 (optional, will be present if the message is binary)
PID=# (optional, will be present only if a non-zero PID value was specified in message submission)
DCS=# (optional, will be present only if a non-zero DCS value was specified in message submission)
UDH=HexString (optional, will be present only if message contains User Data Header)
Data=HexString (optional, will be present only if message is binary)
Text=String (optional, will be present only if message is text)
ReceiptRequested=Yes (optional, will be present only if message is requesting a delivery receipt ... only available in v2009.01.26 and later)

(Note: For SMTP message submissions, only Type, From, and To variables will be present.)

Example:

http://server.name/path?Type=SMSSend&From=UserAccount&To=%2B447777777777&SubmitIP=127.0.0.1&Text=This%20is%20a%20test.

Note that URL escaping is performed when building the URL string. Most HTTP scripting languages will automatically unescape these parameters for you (e.g., %2B is translated back to "+" and %20 is translated back to a space character).