Sending SMS Text Messages

Sending SMS Text Messages over HTTP

To send a text 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 URL parameters. Other sections of this document explain how to send SMS text messages via PHP, Java and a command line interface.

To send an SMS text message via HTTP, use the following URL format:

http://127.0.0.1:8800/?PhoneNumber=xxxxxxxx&Text=abc+def+ghi

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:

http://127.0.0.1:8800/?PhoneNumber=%2B447778001210&Text=abc+def+ghi

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

http://127.0.0.1:8800/?User=username&Password=password&PhoneNumber=xxxxxxxx&Text=abc+def+ghi

Multiple recipients can be included in a URL request by separating them in the “PhoneNumber” parameter with a “,” (comma). For example:

http://127.0.0.1:8800/?PhoneNumber=xxxxxxxx,yyyyyyyy&Text=abc+def+ghi

Or some environments may require the comma character to be URL escaped as %2C. For example:

http://127.0.0.1:8800/?PhoneNumber=xxxxxxxx%2Cyyyyyyyy&Text=abc+def+ghi

There is no limit on the number of recipients that can be specified in a URL request (NowSMS dynamically allocates more memory as required). However, the software that you are using to submit the HTTP request to NowSMS might impose a limit on the HTTP URL length.

The above examples all show HTTP GET transactions. HTTP POST can also be used, with the same variable names and formats, using the standard “form value” MIME type of application/x-www-form-urlencoded.

It is also possible to create distribution lists that are kept on the NowSMS server. These are simple text files that contain a list of phone numbers. You can send a message to a distribution list by specifying the distribution list name in the “PhoneNumber” parameter. (Or you can specify multiple distribution lists or a mix of phone numbers and distribution lists separating each entry with a “,”.) For example:

http://127.0.0.1:8800/?PhoneNumber=DlistName&Text=abc+def+ghi

If the distribution list is a public distribution list, it must be prefaced with the # character when sending to the list. For example:

http://127.0.0.1:8800/?PhoneNumber=#DlistName&Text=abc+def+ghi

For more information about distribution lists, please refer to Editing Distribution Lists and Address Books in NowSMS.

Substitute the text of the SMS message in 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:

%22
< %3C
> %3E
& %26
+ %2B
# %23
% %25
* %2A
! %21
, %2C
%27
\ %5C
= %3D
%E2%82%AC

It is possible to use the “&charset=”xxxxxxx” parameter to indicate that the text has been encoded using a character set other than UTF-8. NowSMS supports any of the character sets supported by Windows. Common “&charset=”xxxxxxxx” settings include “iso-8859-1″ for Western Europe, “iso-8859-6″ for Arabic, and “big5″ for Chinese

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.

If a text message contains text that is outside of the GSM character set, then it is necessary for the message to be sent out using Unicode encoding. When a message is sent with Unicode encoding, only 70 characters can fit into a single SMS message. If a message that contains Unicode characters is longer than 70 characters, one message is sent for every 63 characters of text in the message.

The following table details the characters that are part of the standard GSM character set:

Hex 0x 1x 2x 3x 4x 5x 6x 7x
x0 @ Δ SP 0 ¡ P ¿ p
x1 £ _ ! 1 A Q a q
x2 $ Φ 2 B R b r
x3 ¥ Γ # 3 C S c s
x4 è Λ ¤ 4 D T d t
x5 é Ω % 5 E U e u
x6 ù Π & 6 F V f v
x7 ì Ψ 7 G W g w
x8 ò Σ ( 8 H X h x
x9 Ç Θ ) 9 I Y i y
xA LF Ξ * : J Z j z
xB Ø 1) + ; K Ä k ä
xC ø Æ , < L Ö l ö
xD CR æ - = M Ñ m ñ
xE Å ß . > N Ü n ü
xF å É / ? O § o à

LF = line feed (0x0A)
CR = carriage return (0x0D)
SP = space character (0x20)
1) = Space holder for escape character. This character means that the character is from the GSM default alphabet extension table, and the extension code follows.

Additionally, there are some characters, such as the Euro (€) which are part of an extended GSM character set, which is detailed in the following table:

Hex 0x 1x 2x 3x 4x 5x 6x 7x
x0 |
x1
x2
x3
x4 ^
x5
x6
x7
x8 }
x9 {
xA
xB
xC [
xD ~
xE ]
xF \

If a text message contains only characters that are part of either the standard or extended GSM character set table, then it is subject to the 160 character limit (with the exception that any characters in the extended GSM character set are encoded as two characters instead of one). Otherwise, if the text message contains any characters outside of this character set, the entire message must be encoded in Unicode format, subject to the 70 character limit.

Additional supported URL parameters when sending text messages include:

“Sender” – Specifies the phone number to be included as the sender of the message. (Note: Depending on the configuration of the gateway and the SMSCs to which the gateway connects, this value may be ignored.)

“PID” – Specifies a protocol id field to be associated with the message. The web interface of NowSMS includes checkbox settings for specifying a “Message Type” value. Setting one of the “Replacement Type” values means that if the gateway sends a subsequent message with the same replacement type value, this will replace any previous messages that were sent by the same sender with the same replacement type value. When submitting an SMS message via URL parameters, replacement type values 1 thru 7 correspond to settings of PID=41 thru PID=47.

“DCS” – Specifies the data coding scheme value associated with the message. NowSMS normally sets this value as appropriate (0 indicates a normal text message, and 8 indicates that the message contains Unicode characters). The web interface of NowSMS includes checkbox settings for specifying a “Message Class” value. “Message Class” settings are generally used only for testing, except for “Class 0 (Flash)” messages which can be occasionally useful. A “flash” message is an SMS message that is automatically opened on the display of the receiving phone, and is normally not saved to the phone’s inbox, so that once the user exits the message, the message automatically disappears.

When submitting an SMS message via URL parameters, message class settings of 0 thru 3 correspond to settings of DCS=10 thru DCS=13. Note that NowSMS will automatically convert these DCS values if the message text contains characters that must be encoded using Unicode characters. However, some SMSC connections, such as SMPP, will not support flash messages that contain Unicode text.

For a complete list of URL parameters, please refer to the section Submitting SMS Messages – URL Parameters.