Dynamic SMS Message Routing with HTTP Callbacks

Posted by on Jan 28, 2009 in Support Blog

Topic Keywords: , ,

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://www.nowsms.com/routing-sms-messages-to-a-specifc-smsc-route

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.

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/understanding-sms-accounting-callbacks

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.

Accounting callbacks provide an interface between the NowSMS SMS Gateway and external billing and charging systems.  They can also be used to control message routing, providing a way for a  user application to control which SMSC connections are used for sending particular messages.

These accounting callbacks are HTTP-based. When accounting callbacks are enabled, NowSMS will issue HTTP requests to a customer supplied URL in order to interface with the customer billing and charging systems.

To enable SMS accounting callbacks, it is necessary to manually edit the SMSGW.INI configuration file, and define the callback URL under the [SMSGW] section header, using the following configuration parameter:

SMSAccountingURL=http://server/path

Whenever the SMS Gateway processes an SMS message, it issues an accounting callback by issuing an HTTP transaction to the callback URL. Variables describing the SMS message transaction are appended to the SMSAccoutingURL as HTTP GET CGI-style variables, with standard URL escaping applied for encoding reserved characters.

For 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.

(These variables and transaction types will be described later in this section.)

Accounting callbacks exist primarily to record billing and charging information, however they also can offer the ability to maintain credit control external to NowSMS.

The following accounting callbacks exist for SMS Messaging:

  • SMSSend PreAuth Callback – This callback occurs when a client user account is attempting to submit an SMS message to NowSMS.  The callback can choose to accept or reject the message, and can optionally control message routing and some other message attributes.
  • SMSSend Accounting Callback – This callback occurs when a client user account has submitted an SMS message to NowSMS, and NowSMS has accepted this message for processing.  The callback can choose to accept or reject the message, and can optionally control message routing and some other message attributes.
  • SMSOut Accounting Callback – This callback records that a message has been submitted to an upstream SMSC connection, or has an encountered an error condition or rejection when attempting to be sent to an upstream SMSC connection.
  • SMSIn Accounting Callback – This callback records that an inbound message has been received from an upstream SMSC connection.

This document will only provide details on the SMSSend callbacks, which are relevant for dynamic message routing.

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.  To separate error conditions from active blocking of a message, we recommend that the response include the text “PreAuth=Deny” if the message should be blocked from acceptance.

HTTP clients can submit a single message to multiple recipients.  In this case, normal behaviour for NowSMS is to use a single PreAuth callback specifying the  number of messages that will be sent in the “MsgCount” parameter.  It is possible to override this behaviour and generate a separate PreAuth callback per recipient by setting SMSAccountingPreAuthPerRecip=Yes under the [SMSGW] section header of SMSGW.INI.  (The setting SMSAccountingMustSetRoute=Yes also forces this per recipient callback behaviour.)  If a PreAuth callback rejects one recipient of a multiple recipient message, the entire message will be rejected.  For this reason, it is important to understand that a successful PreAuth callback does not mean that NowSMS has accepted a message for processing.  NowSMS will generate a separate SMSSend Accounting Callback (always one per recipient) when it accepts the message for further processing.

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)

Any defined SMPPOption parameters will also be included.

(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).

The HTTP response can include additional text responses to further control message processing.  These additional responses are expected to appear in the text of the HTTP response, as Name=Value entries appearing with one Name=Value per line of text (e.g., separated by new line characters).

The following Name=Value responses are supported for the SMSSend PreAuth Callback:

PreAuth=Deny

This causes NowSMS to reject the message, and the submitting client will receive a submission error.

SMPPErrorCode=0x#### or ####

Specifies a numeric error code to be returned to the submitting client if the message was submitted via SMPP.  The default error code for a rejected message is 0x0058 (ESME_RTHROTTLED).

RejectMessage=text string

This parameter specifies error text to be returned to the user if the submission interface supports returning such text (e.g., HTTP).

The following Name=Value responses are supported only if SMSAccountingPreAuthPerRecip=Yes or SMSAccountingMustSetRoute=Yes is set under the [SMSGW] section header of SMSGW.INI:

SMSCRoute=routename

If this setting is present in the response, NowSMS will use the specified outbound route name for delivering the message.   (For more information on SMS message routing, see http://www.nowsms.com/routing-sms-messages-to-a-specifc-smsc-route.)  In NowSMS versions 2011.08.11 and later, the SMSCRoute can also take the format localuser:username (the text localuser: followed by a user account name) to indicate that the message should be routed to a local user account instead of an outbound SMSC connection.

Note:  If you are relying on accounting callbacks to set route information, we recommend setting SMSAccountingMustSetRoute=Yes under the [SMSGW] section header of SMSGW.INI.  If this setting is not present, and an accounting callback returns invalid or missing routing information, NowSMS will use its internal routing logic to route the message.   If this setting is present, NowSMS will reject or fail messages if the accounting callback returns invalid or missing routing information.

Further Note:  Routing information can be returned in response to either the SMSSend PreAuth or SMSSend Accounting Callbacks.  If set by the SMSSend PreAuth Callback, any routing response by the SMSSend Accounting Callback will  be ignored and the PreAuth routing information will be used.

RouteCharge=####

If NowSMS credit balances are being used for user accounts, this specifies a charge to be used for the message.  By default, NowSMS assumes 1 credit per message.  This value can support a variable number of credits, including decimal values valid to thousandths of a credit (e.g., .001).

UserData=text

If this value is returned, it will be passed as a parameter to any future SMSSend Accounting Callback referencing this same transaction.  NowSMS versions 2012.02.09 and later will also pass this parameter to any future SMSOut Accounting Callback referencing this same transaction.

Accounting callbacks also have the ability to modify some message attributes (v2011.05.23+), including sender/source address, recipient/destination address and SMPP TLV parameters.  The following Name=Value responses are supported only if SMSAccountingAllowChanges=Yes is set under the [SMSGW] section header of SMSGW.INI: “To=”, “Sender=”, “ServiceType=”, “Validity=”, and “SMPPOption_xxxx=” (SMPPOption_xxxx refers to any optional SMPP TLV parameters that have been configured in NowSMS).  If any of these Name=Value parameters are present, the value specified will replace the existing value in the message being processed.  (In the case of SMPPOption_xxxx= parameters, a blank value will remove the parameter.)  It is recommended that the HTTP response terminate each value with a new line to signal the end of the value string.

 

SMSSend Accounting Callback

This callback is executed after an SMS message that has been submitted by a client user account has been accepted by NowSMS for further processing.

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://www.nowsms.com/routing-sms-messages-to-a-specifc-smsc-route.)

In NowSMS versions 2011.08.11 and later, the SMSCRoute can also take the format localuser:username (the text localuser: followed by a user account name) to indicate that the message should be routed to a local user account instead of an outbound SMSC connection.

Note:  If you are relying on accounting callbacks to set route information, we recommend setting SMSAccountingMustSetRoute=Yes under the [SMSGW] section header of SMSGW.INI.  If this setting is not present, and an accounting callback returns invalid or missing routing information, NowSMS will use its internal routing logic to route the message.   If this setting is present, NowSMS will reject or fail messages if the accounting callback returns invalid or missing routing information.

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)

Any defined SMPPOption parameters will also be included.

(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).

The HTTP response can include additional text responses to further control message processing.  These additional responses are expected to appear in the text of the HTTP response, as Name=Value entries appearing with one Name=Value per line of text (e.g., separated by new line characters).

The following Name=Value responses are supported for the SMSSend Accounting callback:

SMSCRoute=routename

If this setting is present in the response, NowSMS will use the specified outbound route name for delivering the message.   (For more information on SMS message routing, see http://www.nowsms.com/routing-sms-messages-to-a-specifc-smsc-route.)  In NowSMS versions 2011.08.11 and later, the SMSCRoute can also take the format localuser:username (the text localuser: followed by a user account name) to indicate that the message should be routed to a local user account instead of an outbound SMSC connection.

Note:  If you are relying on accounting callbacks to set route information, we recommend setting SMSAccountingMustSetRoute=Yes under the [SMSGW] section header of SMSGW.INI.  If this setting is not present, and an accounting callback returns invalid or missing routing information, NowSMS will use its internal routing logic to route the message.   If this setting is present, NowSMS will reject or fail messages if the accounting callback returns invalid or missing routing information.

Further Note:  Routing information can be returned in response to either the SMSSend PreAuth or SMSSend Accounting Callbacks.  If set by the SMSSend PreAuth Callback, any routing response by the SMSSend Accounting Callback will  be ignored and the PreAuth routing information will be used.

UserData=text

If this value is returned, NowSMS versions 2012.02.09 and later will also pass this parameter to any future SMSOut Accounting Callback referencing this same transaction.

Accounting callbacks also have the ability to modify some message attributes (v2011.05.23+), including sender/source address, recipient/destination address and SMPP TLV parameters.  The following Name=Value responses are supported only if SMSAccountingAllowChanges=Yes is set under the [SMSGW] section header of SMSGW.INI: “To=”, “Sender=”, “ServiceType=”, “Validity=”, and “SMPPOption_xxxx=” (SMPPOption_xxxx refers to any optional SMPP TLV parameters that have been configured in NowSMS).  If any of these Name=Value parameters are present, the value specified will replace the existing value in the message being processed.  (In the case of SMPPOption_xxxx= parameters, a blank value will remove the parameter.)  It is recommended that the HTTP response terminate each value with a new line to signal the end of the value string.

 

For comments and further discussion, please click here to visit the NowSMS Technical Forums (Discussion Board)...