Legacy Sending SMS

This document is describing the methods, and different ways to send SMS through HTTP POST or HTTP GET.

The gateway receives several parameters, which are used to describe what message is to be sent, as well as the intended recipient.
The parameter names are straightforward, for example the parameter describing the recipient is called "to", and the sender is called "from".

The system will automatically split messages longer than 160 characters, into a multipart messages, the receiving handset will display the message as one.

Each segment of the multipart message will be charges as one message.

The webservice is at:

The parameters you submit are analyzed as GET or POST parameters.
Each value of the parameters should be URL Encoded, according to RFC 1738, although a + (PLUS sign) will be interpreted as a space.

A request will look like this:

Error rendering macro 'code': Invalid value specified for parameter 'lang'

http://sms.coolsmsc.dk/?username=xx&password=xx&to=4512345678&from=SMS&message=hello+world&charset=UTF-8

This will send a messages to MSISDN: +4512345678, with the sender ID: "SMS".
The message text will be "hello world" send in charset UTF-8.

Parameters

Name	Type	Description
username	Mandatory	The username for your account.
password	Mandatory	The password which is assigned to the above username.
message	Mandatory	The message which is supposed to be sent. This value should be encoded as windows-1252, unless you have specified another charset in the charset parameter. In case a value is specified in the parameter port, this value should be given as the hexadecimal representation of the binary data you want to send.
to	Mandatory	The intended recipient. This value must include the country code of the intended recipient without any leading + or 00.
from	Mandatory	The sender ID of the message. No more than 11 alphanumeric character or 22 digits. In case the value is alphanumeric, the value should always be encoded as windows-1252.
resulttype		This is used to let the gateway reply to you in different formats. As default it will reply with a describing text with the result. Beside the standard reply format, it also has the possibility to reply with a URL encoded value or in XML format. If the value is "urlencoded" the reply will look like this: var1=val1&var2=val2&var3=val3 In case you specify the value as "xml", the gateway will reply with a XML document.
lang		The language you want the gateway to reply with, it can contain the following values: da for Danish. If this parameter doesn't hold a value it will default to english.
charset		If you are submitting messages in another charset than Windows-1252, you can specify the charset here, and the message will be interpreted with that charset. Please be aware that only valid GSM characters(GSM 03.38 Default Character Set), will be sent correctly. Invalid characters will be replaced with a similar looking character or get stripped from the message. For instance charset could be UTF-8

HTTP Reply

When sending a request to the gateway, the reply will include a header describing the status of the request.
The header is called X-Status and will contain either "success" or "failure", depending on the result of your request.
It is recommended to control the status of the request with this parameter.

The way the gateway replies depends on the value given in "resulttype".

urlencoded

The content is a urlencoded string containing 2 parameters; status and result.

status=STATUS&result=RESULT

The status parameter is either "success" or "failure".
Depending on the result of the request, the parameter result will contain a readable string describing the result.
If the request is successful, the urlencoded string will contain an extra parameter called "msgid". This contains the internal message ID at CoolSMS, and could be used for troubleshooting.

xml

For the XML result, there is a DTD available at this http://sms.coolsmsc.dk/dtd/smsc.dtd

undefined

The content will contain a string describing the result.

Binary messages

With binary messages you can send special message like a nokia vCard or similar.

To send a binary message, you need to specify some extra parameters:

Name	Description
format	When sending a binary message this parameter should contain the value BINARY.
port	The port you want to address on the phone. The port should contain a decimal value, so in case you are used to ports with HEX values such as 158A these should be converted.
message	The message you want to send. The value should contain a binary string.

Class messages

With classes you can define how important a message is, and where it is supposed to be saved on the handset.

There are 4 different classes which can be used:

Name	Value	Description
class	0	The messages is displayed on top of the screen on the handset, and is not saved on the handset unless the user explicitly chooses to save it. This message type is commonly referred to as flash message.
class	1	This class indicated that the message should be saved in the handset memory, either internally or on the SIM storage, depending on the availability.
class	2	The message contains SIM Card data.
class	3	This class indicates that the message should be forwarded to external equipment, it is mostly used on terminal equipment.

If you do not want to use classes or are unsure about its effects, please avoid setting it.

= Unicode

The size of a SMS is limited to 140 Octets, to extend this limit, the 7 bit alphabet, commonly referred to as the GSM Alphabet, has been invented.
This gives the possibility to have 160 characters in each SMS.

Since there are only 7 bits for each character, there is a limited number of available characters.
If you need to send special characters you can use the UNICODE characters instead.
This gives you the possibility to send Russian, Arabic, Chinese, Japanese characters, and others alike.

This limits the number of characters to 70 per message.

To send UNICODE messages the parameter type should be set to UNICODE:

As specified above, you can use the parameter charset to define the charet you have encoded the message in.

If you wish to send the message in HEX, you should put a % in front of all hexadecimal values.

This is an example for an Arabic message:

http://sms.coolsmsc.dk/?username=xxxx&password=xxxx&to=4512345678&from=SMS+HTTP+GW&format=UNICODE&message=%06%2D%06%44%06%48%00%0D%00%0A&charset=UCS-2BE

Wappush

WAPPUSH
Wappush message contains a description and link.
Most handsets gives the possibility to open the link directly when receiving a wappush message.

To send a wappush message, you can use the following parameters:

Name	Type	Description
format	Mandatory	Should be set to WAPPUSH
pushurl	Mandatory	The URL you want to sent to the handset
message	Mandatory	Description of the link the handset is suppose to open
pushexpire		The expiration time of the message. This will default to the current date + 7 days.

To send a wappush with the link http://www.coolsmsc.dk and the description "CoolBIZ", please load the following URL:

http://sms.coolsmsc.dk/?username=xxxx&password=xxxx&to=4512345678&from=SMS+HTTP+GW&message=CoolBIZ&format=WAPPUSH&pushurl=http%3A%2F%2Fwww.coolsmsc.dk

MMS

MMS messages is a presentation with a series of attachments sent to your phone.

To send an MMS message, you can use the following parameters:

Name	Type	Description
format	Required	for MMS messages, the value must be set to MMS
message	Required	Contains the subject of the MMS you are sending
attachment[]	Required	This parameter may occur several times, and contains an URL to the files you want sent with the message.

If you want to send a presentation then the first attachment[] should be a linked to a SMIL file that ends with .smil

To send an MMS message with a picture, and the subject CoolSMS see the following example:

http://sms.coolsmsc.dk/?username=xxxx&password=xxxx&to=4512345678&from=1272&message=CoolSMS&format=MMS&attachment[]=http%3A%2F%2domain.tldF%2image.jpg

Premium Charge

If you want to use premium billing, and have access to the 2-Way module, you can send out charged messages through the gateway.

For premium charged messages, you should specify 2 parameters-

Name	Type	Default	Type	Description
from			Mandatory	From must be set to the given shortcode, you want to use for charged messages.
push_price	INT	0	Mandatory	This should be set to the value which is supposed to be charged.
charity	Boolean	false		Set price to be for a charity or vat exemption. Only allowed for approved users.
invoicetext	String(40)			Invoice text that should be shown on end users phone bill
contenttype	INT	13		See list here

The value is given i Danish øre.

In the examle below, a message is charged from the shortcode 1272, with the value of 1 DKK and 50 Øre.

http://sms.coolsmsc.dk/?username=xxxx&password=xxxx&to=4512345678&from=1272&message=hello+world&push_price=150

Delivery Notifications

To follow the delivery of a SMS message, and possibly see which messages are not delivered, you can request to get sent Delivery Notifications when the message state changes.

The Delivery Notifications are sent with a HTTP GET request, to a URL of your choice.

It is recommended that your system is online 24x7, if your system is not up when a call is made, we will retry every 4 hours, for 24 hours.

To receive Delivery Notifications, please supply the following parameters:

Name	Type	Description
status	Mandatory	To receive Delivery notifications this value should be set to on
statusurl	Mandatory	The URL you wish to receive the status reports
returndata		A 255 octet string, with the customers own reference, for instance an internal id

If resulttype isn't set to a specific value the gateway will return the message id, instead of a describing text.
For other values please refer to the section "HTTP Reply".

When the customer URL is called, it will have the following parameters specified:

Name	Description
msgid	The unique ID of the message
receivetime	UNIX Timestamp for the Delivery Notification
to	The recipient of the message, for which we have status report of
status	The current status
reason	Description of the current status
statuscode	The status code for the message, according to the errorcodes below
returndata	If the returndata parameter was set when sending the message, the parameter will hold the value for the given message of the customer
logdate	The date of when the message was sent, in the format YYYY_mm_dd
mcc	Countrycode
mnc	Operatorcode
push_price	If premium message, the push_price is also sent

Status can contain the following values

Status	Description
received	The message is received
rejected	The message is rejected by the SMSC.(Please see the list of status codes for an explanation)
buffered	The message was not delivered and will try to get sent again at another time
expired	The validity period has expired, the message wasn't delivered

Statuscode

0	Unknown subscriber
1	Service temporary not available
2	Service temporary not available
3	Service temporary not available
4	Service temporary not available
5	Service temporary not available
6	Service temporary not available
7	Service temporary not available
8	Service temporary not available
9	Illegal error code
10	Network time-out
50	Error in MS
100	Facility not supported
101	Unknown subscriber
102	Facility not provided
103	Call barred
104	Operation barred
105	SC congestion
106	Facility not supported
107	Absent subscriber
108	Delivery fail
109	SC congestion
110	Protocol error
111	MS not equipped
112	Unknown SC
113	SC congestion
114	Illegal MS
115	MS not a subscriber
116	Error in MS
117	SMS lower layer not provisioned
118	System fail
119	PLMN system failure
120	HLR system failure
121	VLR system failure
122	Previous VLR system failure
123	Controlling MSC system failure
124	VMSC system failure
125	EIR system failure
126	System failure
127	Unexpected data value
200	Error in address service centre
201	Invalid absolute Validity Period
202	Short message exceeds maximum
203	Unable to Unpack GSM message
204	Unable to convert IRA ALPHANBET
205	Invalid validity period format
206	Invalid destination address
207	Duplicate message submit
208	Invalid message type indicator

104	Operation barred - Deres saldo er ikke høj nok til at gennemfør takseringen
114	Illegal MS - Brugeren har spærret for overtaksering, enten tjenesten, shortcoden eller generelt
209	Refunderet via operatøren

Errorcodes in Excel: Errorcodes.xlsx