SMS URL Parameters for HTTP
To send an SMS message via a menu driven interface, please see the help section titled Web Menu Interface. This section describes how to send a text message programmatically via HTTP URL parameters.
To send an SMS message via HTTP, use the following URL format:
For 127.0.0.1, please substitute the IP address or host name assigned to your gateway PC. (Note: 127.0.0.1 is a local loop back address that can be utilized when you are connecting to the gateway from the same computer.)
For 8800, please substitute the port number that the gateway is configured to use.
Substitute the phone number that you wish to send the SMS message to for the “xxxxxxxx” in the “PhoneNumber” parameter. Use either the local phone number format, or the international phone number format (your network provider may or may not allow you to send to international phone numbers). If the international phone number format is used, note that you must substitute “%2B” for the “+” character, because of URL escaping restrictions. For example, to send an SMS to +447778001210, use the following URL format:
Additional parameters can be added, dependent on the type of message being sent. The following table summarizes available URL parameters:
|URL Parameter||Message Type||Description|
|PhoneNumber||All||Recipient phone number or distribution list name. This field can contain a comma delimited list of recipient phone numbers and/or distribution list names.|
|User||All||If authentication is enabled for the web interface, any application submitting a message must supply a user name and password for access. This user name and password refers to an account defined on the “SMS Users” configuration dialog. The application can either include the user name and password in an “Authorization:” header using “HTTP Basic Authentication”, or it can include the “User” and “Password” parameters in the URL request.|
|Password||All||See “User” parameter above.|
|Text||Text SMS, Binary SMS, WAP Push, WAP OTA Bookmark||For SMS text messages, this specifies the text of the message. For binary SMS messages, this is a string of hexadecimal characters representing the data being sent in the binary message. For WAP Push messages, this is the text associated with a Service Indication (SI) Push. For a WAP OTA Bookmark, this is the text name of the bookmark.|
|Data||Binary SMS||Interchangeable with the “Text” parameter. Officially documented only for binary SMS messages.|
|UDH||Binary SMS||A text string of hexadecimal characters representing the User Data Header (UDH) of the binary SMS message.|
|DCS||Text or Binary SMS (limited usage for text SMS)||A hex value representing the value of the SMS Data Coding Scheme (DCS) for this message. F5 is a common value for most binary SMS message types in GSM environments. Another common DCS setting is 10 for sending a flash (Class 0) message.|
|PID||Text or Binary SMS||A hex value representing the SMS Protocol ID (PID) of this SMS message. The most frequent use of the PID parameter is for sending replacement type messages.|
|Binary||Binary SMS||Set to 1 for binary message submission|
|Sender||All||Sender phone number for this SMS message.|
|Charset||Text SMS||Specifies the character set used for the text in the “Text” parameter. By default, NowSMS assumes UTF-8. NowSMS supports any of the character sets supported by Windows. Common settings include “iso-8859-1” for Western Europe, “iso-8859-6” for Arabic, and “big5” for Chinese.|
|DelayUntil||Text or Binary SMS||This parameter allows messages to be submitted to NowSMS and queued for later processing. The value of this parameter should be of the format “YYYYMMDDHHMM”, indicating the date and time until which the message should be delayed, where YYYY is the year, MM is the month, DD is the day, HH is the hour (in 24 hour format), and MM is the minutes.|
|ReceiptRequested||All||Set to “Yes” if a delivery or non-delivery receipt is requested for this message. (Not supported by all SMSC interfaces.)|
|ReplyRequested||Text SMS||Supported by GSM Modem and SMPP SMSC interfaces only. Set this parameter to “Yes” to set the reply path flag. Technically this indicates that you are requesting that the receiving user be able to send a reply back via the same SMSC through which this message is being submitted. In practice, some users use this setting because some phones will display a prompt on the receiving device indicating that the sender is requesting a reply. (Note that some SMSCs will reject messages sent with this flag, and others may ignore the setting.)|
|VoiceMail||Voice Mail Notification||“On” – Turn on voice mail waiting indication
“Off” – Turn off voice mail waiting indication
“FaxOn” – Turn on fax message waiting indicator
“FaxOff” – Turn off fax message waiting indicator
“EmailOn” – Turn on e-mail message waiting indicator
“EmailOff” – Turn off e-mail message waiting indicator
“VideoOn” – Turn on video message waiting indicator
“VideoOff” – Turn off video message waiting indicator
“OtherOn” – Turn on other message waiting indicator
“OtherOff” – Turn off other message waiting indicator
|VoiceMailMessageCount||Voice Mail Notification||Specifies an optional “message count” for the number of messages waiting associated with this notification.|
|WAPURL||WAP Push||URL to be sent in the WAP Push message.|
|WAPPushInitiatorURI||WAP Push, OMA OTA||Sets the WAP Push Initiator URI. For more information, refer to the Technical Bulletin titled WAP Push or OTA: Unknown Sender.|
|WAPPushFlag||WAP Push, OMA OTA||Sets the WAP Push Flag. For more information, refer to the Technical Bulletin titled WAP Push or OTA: Unknown Sender.|
|WAPSIID||WAP Push (Service Indication)||“Service Indication ID” is a text string that defines an id string to be associated with a service indication push.
If a push has an “WAPSIID” associated with it, it is possible to later send a “WAPSIAction=delete” push with the same “WAPSIID” value to delete the previous push message from the device inbox.
Similarly, if a mobile device receives a push message with a “WAPSIID” that matches that of a previously received push that is still in its inbox, the new push message should replace the existing push message.
|WAPSIACTION||WAP Push (Service Indication)||“Signal Action” specifies the type of alert to be associated with the push. While this is not very widely supported, the general intent is to associate a priority with the alert. Valid settings are:
“signal-high” – high priority alert
“signal-medium” – medium priority alert
“signal-low” – low priority alert
“signal-none” – do not generate a notification alert for this push
“delete” – if a previously sent push exists in the device inbox, with the same WAPSIID as a specified in this push, then the push should be deleted from the device inbox.
|WAPSIEXPIRES||WAP Push (Service Indication)||The “SI Expires” field specifies a date/time at which the receiving device should automatically expire the push. This is a date/time value relative to GMT, in the format “yyyy-mm-ddThh:mm:ssZ”. For example, “2006-02-24T00:00:00Z”.|
|WAPSICREATED||WAP Push (Service Indication)||The “SI Created” field specifies a creation date/time stamp to be associated with the push. If specified, this date/time stamp should take the format “yyyy-mm-ddThh:mm:ssZ”, specifying a date/time value relative to GMT. For example, “2006-02-24T00:00:00Z”.|
|WAPSL||WAP Push (Service Load)||When the “WAPURL” parameter is specified, set this parameter to any value to send the WAP Push as a “Service Load” (SL) message, instead of the default “Service Indication” (SI) message.|
|WAPSLAction||WAP Push (Service Load)||Specifies the type of action to be taken upon receipt of a “Service Load” push. Valid settings are:
“execute-low” – The browser fetches the URL and executes it in a non-intrusive manner
“execute-high” – The browser fetches the URL, executes it and displays it in a manner that may be considered intrusive
“cache” – The browser fetches the URL and saves the resulting data in the browser’s cache (if a cache does not exist, the push is ignored)
|MMSText||MMS Message, Multimedia WAP Push||Text to be included when sending an MMS Message.|
|MMSFile||MMS Message, Multimedia WAP Push||Contains the contents of an uploaded file posted via a form with a MIME encoding of “multipart/form-data”, or specifies a HTTP URL pointing to the file content when specified in a GET request.
This parameter can be repeated multiple times to indicate multiple files to be included in the content of the MMS message.
|MMSSubject||MMS Message, MMS Notification, Multimedia WAP Push||Subject for the MMS Message or MMS Notification Message.|
MMS Notification, Multimedia WAP Push
|Sender for the MMS Message or MMS Notification Message|
|MMSDeliveryReport||MMS Message||“Delivery Report specifies whether or not a delivery report is requested for the message. Set to “Yes” to request a delivery report. Note that any delivery report would be directed back to the phone number or e-mail address specified in the “MMSFrom” address.|
|MMSReadReport||MMS Message||“Read Report” specifies whether or not a read receipt is requested for the message. Note that the receiving client may choose not to send a read receipt. Any read receipt report would be directed back to the phone number or e-mail address specified in the “MMSFrom” address.|
|MMSPriority||MMS Message||“Priority” is a user defined priority to be associated with the message. Generally, any priority definition associated with the message is ignored by the underlying transport, but the receiving client may decide to display messages differently based upon this priority setting.|
|MMSMessageClass||MMS Message||“Message Class” is an attribute defined in the MMS specifications. “Personal” is the message type that is used for standard user-to-user communications. Other defined message classes that are supported by this parameter include:
|MMSForwardLock||MMS Message, Multimedia WAP Push||Forward locking is the most basic level of DRM (Digital Rights Management). When “Forward Lock” is set to “Yes”, this indicates that the receiving device should not allow any non-text objects in the message to be forwarded off of the device. The device may allow the user to extract pictures, videos or sounds from the message and save them on the phone. However, any such objects remain forward locked, such that they cannot be forwarded to another user or transferred to another device.|
|DRMRestrict||MMS Message, Multimedia WAP Push||Beyond forward locking, More advanced DRM (Digital Rights Management) restrictions can be applied to limit the number of times that the user can access an object, or start and end dates can be specified to limit how long the user can access an object.
These advanced DRM restrictions can be applied by setting “DRMRestrict” to “Yes”. When this setting is enabled, forward lock is also implied, and the value of the “MMSForwardLock” setting is ignored.
|DRMRestrictTextXML||MMS Message, Multimedia WAP Push||“Yes” specifies that the rights object should be encoded in text XML format. “No” specfies that the rights object should be encoded in binary XML format. The default is “No”.|
|“DRM Permissions” specify what types of access are allowed against the objects in a message that is protected with DRM.
For example, an audio or video object requires “Play” permission before the user can access it. An image requires “Display” permission before the user can access it, and it requires “Print” permission if the user is to be allowed to print the image to a printer , perhaps over Bluetooth. An application requires “Execute” permission before the user can make use of the application. In all cases, the forward locking is assumed, so that the user is not allowed to forward or transfer the object from the device.
If you are sending multiple types of objects in the MMS message, check all permissions that are required for the different types of objects that are being sent.
|DRMPermissionPlay||MMS Message, Multimedia WAP Push||Set to “Yes” to enable DRM “Play” Permission.|
|DRMPermissionDisplay||MMS Message, Multimedia WAP Push||Set to “Yes” to enable DRM “Display” Permission.|
|DRMPermissionExecute||MMS Message, Multimedia WAP Push||Set to “Yes” to enable DRM “Execute” Permission.|
|DRMPermissionPrint||MMS Message, Multimedia WAP Push||Set to “Yes” to enable DRM “Print” Permission.|
|“DRM Constraints” specify constraints with regard to how long a DRM protected object object should remain accessible to the user.
It is possible to specify one or more of these constraints that follow.
|DRMConstraintCount||MMS Message, Multimedia WAP Push||“# of Accesses (count)” specifies the the user can only access the DRM protected object this number of times before access is no longer allowed.|
|DRMConstraintStart||MMS Message, Multimedia WAP Push||“Start Date (yyyy-mm-dd)” specifies that the user will not be allowed to access the DRM protected object until on or after the specified date. (Note that you must specify the date in yyyy-mm-dd format, e.g., 2006-02-24.)|
|DRMConstraintEnd||MMS Message, Multimedia WAP Push||“End Date (yyyy-mm-dd)” specifies that the user will not be allowed to access the DRM protected object after the specified date. (Note that you must specify the date in yyyy-mm-dd format, e.g., 2006-02-24.)|
|DRMConstraintInterval||MMS Message, Multimedia WAP Push||“# of Days (interval)” specifies that the user will be allowed to access the DRM protected object for this number of days after initial receipt of the object. The user can either enter a number of days here, or they can enter any valid value defined for the “<interval>” element in the OMA DRM Rights Expression Language specification. For example, P2Y10M15DT10H30M20S represents a duration of 2 years, 10 months, 15 days, 10 hours, 30 minutes and 20 seconds.|
|MMSWAPPush||Multimedia WAP Push||Set to “Yes” to indicate that the message being sent should be sent as an “Multimedia WAP Push” message instead of as an MMS message.|
|MMWAPTemplate||Multimedia WAP Push||Specifies a WML template to be used for generating the Multimedia WAP Push message. Please refer to the NowSMS discussion board for more information.|
|MMWAPURLOnly||Multimedia WAP Push||If set to “Yes”, specifies that NowSMS should return a URL pointer for a dynamically generated “Multimedia WAP Push” in the HTTP response, however NowSMS does not generate the actual WAP Push message for sending the content. Please refer to the NowSMS discussion board for more information.|
|MMSURL||MMS Notification||URL that contains the MMS Message content for which an MMS Notification Message should be generated.|
|MMSURLValidate||MMS Notification||Normally, when NowSMS generates an MMS Notification, it first validates that the specified “MMSURL” can be retrieved, and that it is of a valid format. Include this parameter, set to “No” to disable this validation check.|
|WAPBookmark||WAP Bookmark||URL to be sent as a WAP OTA bookmark (not supported by many devices).|
|OTA||WAP OTA Config||Name of an “.ota” file in the OTA subdirectory which contains WAP OTA configuration information, or value “POST” when OTA content is being submitted via HTTP POST.|
|OTAOMA||OMA Provisioning Content OTA||Name of an “.ota” file in the OTA subdirectory which contains an OMA Provisioning Content document, or value “POST” when provisioning content is being submitted via HTTP POST.|
|OTAPINTYPE||OMA Provisioning Content OTA||Specifies the type of PIN specified in the OTAPIN variable. Can either be a value of USERPIN, NETWPIN, or USERNETWPIN.|
|OTAPIN||OMA Provisioning Content OTA||The value of this parameter depends upon the value of the OTAPINTYPE parameter.
USERPIN – The PIN a short PIN code (often 4 digits). When the user receives the OTA settings message, they will need to supply this PIN code in order to be able to open the message and apply the settings.
NETWPIN – The PIN is a network PIN code. In the GSM environment, this is the IMSI number associated with the SIM card in the device. (Hint, if you want to experiment with determining the PIN card associated with a SIM, you can put the SIM into a GSM modem and the AT+CIMI command to return the IMSI. However, not all GSM modems support the AT+CIMI command.) When the device receives the settings, if the NETWPIN does not match the IMSI, the settings will be discarded.
USERNETWPIN – The PIN is a combination of the USERPIN and NETWPIN types. Define the OTA PIN as the IMSI number associated with the SIM card in the device, followed by a “:” character, followed by a USERPIN (e.g., 1234567889012345:1234). When the device receives the settings, the user will be prompted for a PIN. This user supplied PIN, and the SIM card IMSI, must match in order for the settings to be accepted.
|Validity||All||Supported by outbound GSM modem and SMPP SMSC connections only. This parameter specifies a validity period for the message as an interval defined in hours, minutes or days. If the SMSC cannot deliver the message within the specified validity period, the SMSC is instructed to discard the message. (Note that this setting is not supported by all SMSCs.) Specify ##D for a validity period in days, ##H for a validity period in hours, or ##M for a validity period in minutes, where ## is a numeric value (e.g., 30D for 30 days or 7H for 7 hours).|
|ContinueURL||All||URL to continue to after SMS message submission.|
|SourcePort||All||Specifies the source port number as a hex string, that is associated with the sender address of this message. (Used for application/port addressing of messages to Java MIDlets.)|
|DestPort||All||Specifies the source port number as a hex string, that is associated with the recipient(s) of this message. (Used for application/port addressing of messages to Java MIDlets.)|
|BillingInfo||All||Supported by outbound UCP/EMI SMSC connections only. This parameter specifies a value to be included as the “billing info” parameter in the outbound SMS message, when it is sent via a UCP/EMI connection.|
|ServiceType||All||Supported by outbound SMPP SMSC connections. This parameter specifies a value for the “service_type” parameter in the outbound SMS message when it is sent via an SMPP connection.|
|LocalUser||All||Indicates that the message should be routed to a local “SMS Users” account supplied as the parameter value. The account must have SMPP or SMTP Login enabled to support receiving messages.|
|InboundMessage||All||Set to “Yes” to indicate that this is an inbound/received message that should be routed to the 2-way command processor instead of being routed to an outbound SMSC connection.|
|SMSCRoute||All||Specifies the name of an SMSC through which this message should be routed (e.g., “Bluetooth Modem” or “SMPP – a.b.c.d:xyz”).
Or, instead of using a specific SMSC name, it can be a route name that is defined as associated with one or more SMSCs. To define a route name for an SMSC, it is necessary to manually edit SMSGW.INI, and under the appropriate section header (e.g., [Modem – Bluetooth Modem] or [SMPP – a.b.c.d:xyz]), add RouteName=xxxxx. It is possible for multiple SMSCs to share the same route name, meaning that if a message is submitted via HTTP with the “&SMSCRoute=xxxxx” parameter, it will be routed outbound over the first available SMSC that is configured with the RouteName=xxxxx setting.
|EMSText||EMS Text||The “EMSText” parameter defines an EMS text message to be sent. This text can include EMS attributes for text formatting, such as bold, italics and large or small text. EMS text messages can also included predefined animations and sounds which are pre-loaded on EMS compatible phones. NowSMS also supports generating the EMS text formatting codes to specify colors to be used in text messages, however this functionality does not appear to be very widely supported in current handsets. NowSMS implements special tags to indicate EMS attributes in the “EMSText” parameter. For more information on these tags, please see Sending EMS Messages.|
|RingToneDataText||EMS Ringtone||A text string that contains ring tone data in either RTTTL, iMelody or MIDI format. (MIDI is a binary format, therefore MIDI data must be represented as a hex string when using this parameter.)|
|RingToneDataFile||EMS Ringtone||Ring tone data submitting using HTTP file upload. The file can contain ring tone data in either RTTTL, iMelody or MIDI format. (Note: This parameter can only be used in an HTTP POST with the content type of multipart/form-data.)|
|RingToneDataURL||EMS Ringtone||HTTP URL pointer to a ring tone file residing on another web server. The ring tone file can be in either RTTTL, iMelody or MIDI format.|
|RingToneOut||EMS Ringtone||Specifies the output format to be used for the ring tone:
“Nokia” (Nokia Smart Messaging) – This is the binary encoding for RTTTL, which was originally defined by Nokia. (Note that NowSMS currently only supports the sending these messages out in binary format. The text “//SCKL” format may be supported in a future release.)
“EMS” (EMS – iMelody) – The ring tone is converted to iMelody, if necessary, and encoded as an EMS message.
“EMSShort” (EMS Short Format – iMelody without headers) – The ring tone is converted to iMelody, if necessary. As EMS can be rather verbose, the headers are stripped from the iMelody data, and it is then encoded as an EMS message.
“WAPPush” (WAP Push – MIDI or no conversion) – If the input ring tone is in RTTTL or iMelody format, it is converted to MIDI. Otherwise, no conversion is performed. The output ring tone is delivered as a WAP Multimedia Message.
|PictureMessageDataText||EMS Picture Message||A text string that contains image data in either BMP, JPEG or GIF format. (These are all binary formats, therefore the image data must be represented as a hex string when using this parameter.)|
|PictureMessageDataFile||EMS Picture Message||Image data submitting using HTTP file upload. The file can contain image data in either BMP, JPEG or GIF format. (Note: This parameter can only be used in an HTTP POST with the content type of multipart/form-data.)|
|PictureMessageDataURL||EMS Picture Message||HTTP URL pointer to an image file residing on another web server. The image file can be in either BMP, JPEG or GIF format.|
|PictureMessageOut||EMS Picture Message||Specifies the output format to be used for the picture message:
“Nokia” (Nokia Smart Messaging) – This binary encoding format was originally defined by Nokia. (Note that NowSMS currently only supports the sending these messages out in binary format. The text “//SCKL” format may be supported in a future release.)
“EMS” – The image is converted to EMS format, if necessary, and encoded as an EMS message.
“WAPPush” (WAP Push – no conversion) – No conversion is performed on the image, and it is delivered as a WAP Multimedia Message.
|SMPPOption_*||All||See SMSGW.INI, [SMPPOptions] in “Advanced Configuration Settings”.|
When a text message is being submitted via the “Text” parameter, note that due to URL escaping restrictions, space characters should be replaced with “+” characters. Also, certain special characters, such as “?”, “&”, “:” and “=” need to be replaced with an escape character. The gateway expects characters to be encoded in UTF-8 (Unicode-based) format, therefore some characters, including the Euro (€) may require multiple escaped characters. (Note: The Web Menu Interface automatically performs this escaping.) The following table shows common characters that must be escaped:
Message text up to 160 characters in length can be sent in a single SMS message. The gateway automatically supports the sending of longer messages by utilizing “concatenated SMS” to send messages larger than 160 characters in length. Note that some older mobile phones will not support longer SMS messages. For longer SMS messages, one message is sent for every 153 characters of text in the message.