Sending SMS WAP Push messages using the ActiveXperts SMS and MMS Toolkit.

Service Indication

What is WAP Push ?

WAP Push, has been incorporated into the specification to allow WAP content to be pushed to the mobile handset with minimum user intervention. A WAP Push is basically a specially encoded message which includes a link to a WAP or WWW address. WAP Push is specified on top of WDP (WAP Datagram Protocol, resembled the UDP protocol in the Internet); as such, it can be delivered over any WDP-supported bearer, such as GPRS or SMS.

In most GSM networks, however, GPRS activation from the network is not generally supported, so WAP Push messages have to be delivered on top of the SMS bearer. The network entity that processes WAP Pushes and delivers them over an IP or SMS Bearer is known as a Push Proxy Gateway To receive WAP Push messages on your phone, it has to be WAP version 1.2 enabled.

There are 2 types of WAP Push messages. We will discuss the Service Indication message here. For more details on sending Service Load messages click here. Service Indication messages are used to notify the user that new WAP content is available, Service Load messages forces the phone to go directly to the content without user intervention (depending on the security level of your mobile phone).

WAP Push messages are encoded as XML. Because the XML format is not suitable for low bandwidth applications such as SMS, the messages are encoded using WBXML which stands for WAP Binary XML. When a message is encoded using this standard, common tags and attribute values are replaced with a single byte.

The full specification of this format van be found at www.w3.org.

Sample of a WAP Push message (Service Indication) in XML:

<?xml version="1.0"?>
<!DOCTYPE si PUBLIC "-//WAPFORUM//DTD SI 1.0//EN" "http://www.wapforum.org/DTD/si.dtd">
<si>
<indication href="http://wap.yahoo.com" action="signal-medium" si-id="6532" >
  WAP Push Message
</indication>
</si>

The same WAP Push message in WBXML (excluding the WSP header) :

0x02                  WBXML Version 1.2
0x05                  SI 1.0 Public Identifier
0x6A                  Charset UTF-8
0x00                  String Table Length ( = 0 )
0x45                  <si>
0xC6                  <indication 
0x0C                  href="http:// 
0x03                  start of string value 
0x77                  'w'
0x61                  'a'
0x70                  'p'
0x2E                  '.'
0x79                  'y'
0x61                  'a'
0x68                  'h'
0x6F                  'o'
0x6F                  'o'
0x2E                  '.'
0x63                  'c'
0x6F                  'o'
ox6D                  'm'
0x00                  end of string value
0x11                  si-id attribute
0x03                  start of string value
0x36                  '6'
0x35                  '5'
0x33                  '3'
0x32                  '2'
0x00                  end of string value
0x07                  action attribute ( signal - medium )
0x01                  > ( end of attributes )
0x03                  start of string value
0x57                  'W'
0x61                  'A'
0x70                  'P'
0x20                  ' '
0x50                  'P'
0x75                  'u'
0x73                  's'
0x68                  'h'
0x20                  ' '
0x4D                  'M'
0x65                  'e'
0x73                  's'
0x73                  's'
0x61                  'a'
0x67                  'g'
0x65                  'e' 
0x00                  end of string value
0x01                  </indication>
0x01                  </si>

Using the WAP Push object

The SMS and MMS Toolkit makes it easy to generate and deliver WAP Push messages. You can send WAP Push messages using a GSM modem (or GSM phone), or using an SMPP provider. Use the WapPush object to format the message of the SMS, and use the regular GsmOut or Smpp functions to send the Wap Push formatted message.

The following code snippet shows how to encode the WAP Push message as shown above:

Set objWap              = CreateObject ( "ActiveXperts.SmsDataWapPush" )
Set objConstants        = CreateObject ( "ActiveXperts.SmsConstants" )

objWap.ConnectionType   = objConstants.asWAPPUSH_SERVICE_INDICATION
objWap.URL              = "http://wap.yahoo.com"
objWap.Description      = "WAP Push Message"
objWap.SignalReference  = "6532"
objWap.SignalAction     = objConstants.asWAPPUSHSIGNAL_MEDIUM

objWap.Encode

Used Parameters

ConnectionType

Specifies whether this is a Service Indication or Service Load WAP Push message. The most common used WAP Push type is the Service Indication. The following values are valid:

Value ActiveXperts Value/Constant
"service-indication" asWAPPUSH_SERVICE_INDICATION (0)
"service-load" asWAPPUSH_SERVICE_LOAD (1)

URL

The URL of the website we want to send the mobile to. The maximum length of this URL is 255 characters. The URL has to start with "http://" or "https://".

Title

The description for the content that has to be loaded on the mobile phone. The maximum length of this Title is 50 characters.

SignalReference

This value is optional. This reference is mostly used to delete the message from the mobile phone as soon as the site is visited ( for instance: webmail notifications ). When you send a WAP Push message with the same reference, any message on the phone with the same reference will be replaced ( or deleted depending on the signal action ).

SignalAction

Specifies how the WAP Push message is displayed on the mobile phone. If this value is not specified, "signal-medium" will be used.

The following values are valid:

XML ValueActiveXperts Value/ConstantWBXML Value
"signal-none"asWAPPUSHSIGNAL_NONE (0)0x05
"signal-low"asWAPPUSHSIGNAL_LOW (1)0x06
"signal-medium"asWAPPUSHSIGNAL_MEDIUM (2)0x07
"signal-high"asWAPPUSHSIGNAL_HIGH (3)0x08
"signal-delete"asWAPPUSHSIGNAL_DELETE (4)0x09

"signal-none"

The message is delivered to the WAP Push inbox of the mobile phone without notifying the user.

"signal-low", "signal-medium" and "signal-high"

This signal actions specify how the message should be displayed on the mobile phone.

For instance:

"signal-low": Only display the message on the screen, no sound.
"signal-medium": Display the message and alert the user with a single beep.
"signal-high": Display the message and alert the user with a ringing tone.

Most of the mobile phones do not distinguish between above values, they thread every message as "signal-medium".

"signal-delete"

When a signal reference is specified, the "signal-delete" action will delete all WAP Push messages with the same reference from the mobile phone. This can be used to automatically delete a WAP Push message from the recipients phone when they visited the URL sent in a previously sent message.

Sending the encoded data

After all parameters has been set, you have to call the "Encode" function. This function does the actual encoding and stores the encoded push message in the 'EncodedMessage' property.

If the "Encode" functions failes, you can check the "LastError" property to see what is going wrong.

The encoded data can be send using the SmsProtocolSmpp or SmsProtocolGsm object. Sending WAP Push messages using the SmsProtocolDialUp object is not supported.

To retrieve an encoded message from the object, you have to use the 'EncodedMessage' property. Please note that you have to set the messagetype to "asMESSAGETYPE_DATA_UDH" because the WAP Push data is encoded as 8 bit message data and includes UDH information for application port addressing. The samples below demonstrates how to send the messagedata using the SmsProtocolSmpp and SmsProtocolGsm objects:

SmsProtocolSmpp:

' WAP Push VBScript sample

   objSmsProtocol    = CreateObject ( "ActiveXperts.SmsProtocolSmpp" )
   objSmsMessage     = CreateObject ( "ActiveXperts.SmsMessage" )
   objSmsConstants   = CreateObject ( "ActiveXperts.SmsConstants" )
 
   objWap.Encode
  
   objSmsProtocol.Server            = "smpp.activexperts-labs.com"
   objSmsProtocol.SystemID          = "AX008"
   objSmsProtocol.SystemPassword    = "812056"
   
   objSmsProtocol.Connect

   WScript.Echo "Connect, result #" & objSmsProtocol.LastError

   If ( objSmsProtocol.LastError <> 0 ) Then
     WScript.Quit
   End If

   objSmsMessage.Format      = objSmsConstants.asMESSAGEFORMAT_DATA_UDH
   objSmsMessage.Data        = objWap.EncodedMessage
   objSmsMessage.Recipient   = "+31647134225"

   objSmpp.Send ( objSmsMessage )

   objSmpp.Disconnect

SmsProtocolGsm:

objSmsProtocol  = CreateObject ( "ActiveXperts.SmsProtocolGsm" )
objSmsMessage   = CreateObject ( "ActiveXperts.SmsMessage" )
objSmsConstants = CreateObject ( "ActiveXperts.SmsConstants" )
   
objWap.Encode
   
' Set Device
objSmsProtocol.Device           = "COM1"

' Set Message Properties
objSmsMessage.Format            = objSmsConstants.asMESSAGEFORMAT_DATA_UDH
objSmsMessage.Recipient         = "+31647134225"
objSmsMessage.Data              = objWap.EncodedMessage

objSmsProtocol.Send ( objSmsMessage )