Sending an SMS using HTTP

Overview

The MX Telecom SMS Server allows SMS messages to be sent using HTTP. This page details the format of the HTTP requests which can be made to the MX Telecom SMS Server.

Contents

• Sending an SMS Text Message using HTTP GET
• Parameters for all messages
• Response from the server
• Plain text (ISO-8859-15) messages
• GSM character set (IA5) messages
• Unicode (UCS2) messages
• vCard entry
• vCalendar entry
• SMS with UDH
• Data message without UDH
• WAP Push Service Indication
• MMS Notification

For details on sending other, less-common message types, please click here.

Sending an SMS Text Message using HTTP GET

The MX Telecom SMS Server exposes an HTTP interface allowing applications with internet connectivity to send SMS text messages.

A request for a page using the structure shown below is all that is needed for you to send an SMS through the MX Telecom SMS Server. The endpoints for these HTTP requests are http://sms.mxtelecom.com/SMSSend for HTTP and https://sms.mxtelecom.com/SMSSend for HTTPS (SSL).

Messages should be sent as a HTTP GET or POST using the parameters listed below. One request should be sent per message.

HTTP/1.1 is enabled so, if sending multiple packets, the TCP/IP connection should be kept open between requests. If sending message with a high transmission rate is required, then several persistant HTTP/1.1 connections should be used concurrently (perhaps 3 or 4). Pipelining requests (ala Mozilla) is supported but encouraged only where necessary (ie with high message rates and large latency between customer and MX Telecom).

Parameters for all messages

Several parameters are common to all message types, and should be included in the HTTP request regardless of the specific method being invoked. Details of these parameters are as follows:

Name	Description
user	Username of the account to send through
pass	Password
smsto	MSISDN of the message recipient (eg 447771824154). No leading "+" is required
*smsfrom	Originator for the message (ignored for accounts where changing the originator is not possible). Where valid this can be numeric (maximum 16 digits) or alphanumeric (maximum 11 digits)
*note	Note that will be stored in the billing record (maximum 160 characters)
*subaccount	Sub account that will be stored in the billing record (maximum 10 characters)
*report	Flags for delivery reports (These are bit fields, ie report=7 enabled all reports - default=0): Bit 1 - Enable intermediate delivery reports Bit 2 - Enable success delivery reports Bit 3 - Enable failure delivery reports
*vp	Validity period for the message, in seconds

(Optional parameters are indicated by a *)

The following example shows the common structure of all HTTP requests understood by the MX Telecom SMS Server:

http://sms.mxtelecom.com/SMSSend?user=myusername&pass=mypassword&smsfrom=1234
  &smsto=44778148446&...other parameters...

Along with these parameters, there are a variety of other parameters which are needed for the message body, depending on your preference for the encoding/content of the message.

Parsing responses to GET requests

The responses to GET requests have now been changed to take into account standard internet three digit reply codes: broadly speaking, 20x implies success, 40x implies bad request, and 50x implies server errors.

When a message is sucessfully received by the MX Telecom SMS Server a HTTP success will be returned to the caller (200 code) and the HTTP body will contain one or more message identifiers. These identify messages, and will be used in delivery reports.

Plain Text example:

GET /SMSSend?user=username&pass=password&smsfrom=1234&smsto=44778148446
   &smsmsg=Hello HTTP/1.1
Host: sms.mxtelecom.com

HTTP/1.1 200 OK
Date: Tue, 25 Jun 2002 13:00:20 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked

9
21343457

0

Multi-part message example:

GET /SMSSend?user=username&pass=password&smsfrom=1234&smsto=44778148446&logo_type=
   PICTURE&smsmsg=Hello&img=89504e470d0a1a0a0000000d49484452000000480000001c0103
   000000f83c6be500000006504c5445000000ffffffa5d99fdd00000001624b47440088051d480
   00000d94944415478da358e318ac26010855fd6620bcbb5b7703b1b0bc1321ec2c1c22207d80b
   586996bd86a0f59f22365a08a282a596b2ed160b4a1a450c09a2794e4c9ce2f1f1bd1918f0397
   19fc828b45f140c09c072814f8758e2ad09eb3058691b2fc87f27dd5b7e93a7454a755874fb45
   30b93636caeaee97ea7454785250d9b6ec75178c5bd5ae2a7531a6b033fa19bff3f6b1076f1d3
   755ea12645f68ba059e6b7f25303a4647e6b728e76d3e2ff289df8cda84e7930e032f81b49399
   e7efe40e6328e218ef0a912830739150dd8cf2a5a94e7a66128a3c005faab5918832af3200000
   00049454e44ae426082 HTTP/1.1
Host: sms.mxtelecom.com

HTTP/1.1 200 OK
Date: Mon, 01 Jul 2002 17:01:38 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked

1b
22098253
22098254
22098255

0

(Note that the numbers either side of the message ids are present as a result of the "chunked" transfer-encoding and will be stripped out by a browser or other transfer agent.)

In the case of a forbidden operator (invalid username/password or attempting to send a reverse billing message where not allowed) the servlet will return an HTTP Forbidden error (code 403) and the body will contain an error message.

GET /SMSSend?user=username&pass=incorrectpassword&smsfrom=1234&smsto=44778148446
        &smsmsg=Hello HTTP/1.1
Host: sms.mxtelecom.com

HTTP/1.1 403 Forbidden
Date: Tue, 25 Jun 2002 12:59:31 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked

20
Forbidden
 Bad username/password
0

In the case of a bad request - eg parameters missing/invalid the servlet will return a Bad request error (code 400).

GET /SMSSend?user=username&pass=incorrectpassword&smsfrom=1234
        &smsto=44778148446 HTTP/1.1
Host: sms.mxtelecom.com

HTTP/1.1 403 Forbidden
Date: Tue, 25 Jun 2002 12:59:31 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked

21
Bad Request
 Request type unknown
0

If there is a problem with the MX Telecom server then a 500 Internal server error will be returned. The customer should wait a few seconds and reattempt to send their message.

Plain text messages

The HTTP request should include the common parameters described above, in addition to the following plain-text-specific parameters:

Parameter	Description
smsmsg	The message text
*flash	0 - No flash (Default) 1 - Flash
*split	0 - Don't split long messages. Messages > 160 characters will be rejected. (Default) 1 - Split messages using "..." (Maximum of 5 messages once split) 2 - SMS Concatenation (w. UDH header) - not supported by all phones (Maximum of 4 messages once split) 3 - Split messages into multiple 160 character messages (Maximum of 5 messages once split)

(Optional parameters are indicated by a *)

The example below shows a typical HTTP request for a message of this sort:

http://sms.mxtelecom.com/SMSSend?user=myusername&pass=mypassword&smsfrom=1234
  &smsto=44778148446&smsmsg=Hello%20World

An form for this message type can be found here.

Or to send a flash message:

http://sms.mxtelecom.com/SMSSend?user=myusername&pass=mypassword&smsto=44778148446
  &smsfrom=flash&smsmsg=Flashy%20Message&report=7&flash=1

An example HTML form for this message type can be found here.

This will send a message from the account of user username, with password mypassword, to recipient number 44778148446, with the originator of the message set to 1234 (this may not always be possible). The message, in this case Hello World must be suitably URL encoded (eg the %20 rather than a space).

Along with these parameters, there are a variety of other parameters which are needed for the message body, depending on your preference for the encoding/content of the message.

GSM character set (IA5) messages

Parameter	Description
smsia5	The message text (as for ISO-8859-15 above but will be treated as IA5 (i.e. should still be 1 octed per character)
*flash	0 - No flash (Default) 1 - Flash
*split	0 - Don't split long messages. Messages > 160 characters will be rejected. (Default) 1 - Not yet implemented: Split messages using "..." etc. 2 - SMS Concatenation (w. UDH header) - not supported by all phones
*smsudh	Optional hex encoded User Data Header (can only be used when split=0)

(Optional parameters are indicated by a *)

Unicode (UCS2) messages

Parameter	Description
smsucs2	The message text as hex encoded UCS2
*flash	0 - No flash (Default) 1 - Flash
*split	0 - Don't split long messages. Messages > 70 unicode characters will be rejected. (Default) 1 - Not yet implemented: Split messages using "..." etc. 2 - SMS Concatenation (w. UDH header) - not supported by all phones
*smsudh	Optional hex encoded User Data Header (can only be used when split=0)

(Optional parameters are indicated by a *)

vCard entry

Parameter	Description
vcard_data	The vcard to send

The example below shows a typical HTTP request for a message of this sort:

http://sms.mxtelecom.com/SMSSend?user=myusername&pass=mypassword&smsto=44778148446
  &smsfrom=vCardSender&subaccount=&note=&vcard_data=BEGIN%3AVCARD%0D%0AVERSION
  %3A2.1%0D%0AFN%3AJohn+Smith%0D%0ATEL%3BWORK%3BVOICE%3A442071231234%0D%0ATEL
  %3BMOBILE%3BVOICE%3A447970123456%0D%0ATEL%3BHOME%3BFAX%3A442071231235%0D%0A
  END%3AVCARD 

An example HTML form for this message type can be found here.

vCalendar entry

Parameter	Description
vcalendar_description	Description for the event
vcalendar_date_start	Start time
vcalendar_date_end	End time
vcalendar_audio_alarm	Alarm time

Time format: yyyyMMddThhmmss y=year, M=month, d=day, h=hour m=minute, s=sec.

The example below shows a typical HTTP request for a message of this sort:

http://sms.mxtelecom.com/SMSSend?user=myusername&pass=mypassword&smsto=447974128549
  &smsfrom=myDiary&vcalendar_description=Test+Appointment&vcalendar_date_start
  =20001110T113000&vcalendar_date_end=20001110T120000&vcalendar_audio_alarm
  =20001110T110500

An example HTML form for this message type can be found here.

SMS with UDH

Parameter	Description
smsudh	User data header. Encoded into hex
*bits	Describes the content of the message body: 7 - 7bit text (eg EMS messages) 8 - 8bit data (eg Nokia SmartMessaging) (Default) 16 - 16bit data (eg UCS2 messages)
smsmsg	Body of the message If bits=8 or 16:  This parameter is mandatory  8 bit message data. Encoded into hex If bits=7:  This parameter is optional  The text of the message (ISO-8859-1)

(Optional parameters are indicated by a *)

An example HTML form for this message type can be found here.

Data messages without UDH

Parameter	Description
bits	Describes the content of the message body: 8 - 8bit data (eg Nokia SmartMessaging) (Default)
smsmsg	Body of the message encoded into hex

(Optional parameters are indicated by a *)

WAP Push Service Indication

Parameter	Description
pushtype	0 - Type of WAP Push
push_href	This attribute specifies the URI that is used to access the service. If href is empty, or omitted, the SI corresponds to a notification (no service can be initiated).
push_action	This attribute may contain a text string specifying the action to be taken when the SI is received. 0 - signal-none 1 - signal-low : The SI MUST be postponed without user intervention. 2 - signal-medium : The SI MUST be presented as soon as the implementation allows that to be carried out in a non-user-intrusive manner. 3 - signal-high : The SI MUST be presented as soon as the implementation allows that to be carried out in a non-user-intrusive manner, or earlier if considered appropriate (which MAY result in a user-intrusive behaviour). This decision can either be based on user preference settings or be carried out at the discretion of the implementation. 4 - signal-delete : If the received SI's action attribute equals "delete", both the received SI and any other (if any) SI with identical si-id MUST be deleted. An SI with the action attribute set to "delete" MUST have an explicitly assigned value for si-id.
*push_siid	This attribute may provide the SI with an identity in order to make it possible to distinguish between different SIs. If this attribute is not specified, its value is considered to be the same as the value of the href attribute. In order avoid conflicts between SIs, it is RECOMMENDED that content developers use an address (e.g. URL) within their control combined with an identifier for the SI as the value for si-id (for example: www.wapforum.org/siid/123 or 123@siid.wapforum.org ). This parameter is required if a push_action of signal-delete is specified.
push_siname	Name of the Service Indication
*push_siexpires	This attribute may be used to specify the date and time when the SI expires and thereby be automatically deleted or marked as expired . If this attribute is not specified, the SI never expires and is thus not subject to automatic deletion. The representation for this attribute value is the same as the one used for the created attribute.
*push_initiator	The name of the initiator of the WAP Push (appears as the originator on some handsets)

For full details on the WAP 1.2 Push Service Indication see WAP Service Indication Specification.

The example below shows a typical HTTP request for a message of this sort:

http://sms.mxtelecom.com/SMSSend?user=myusername&pass=
	mypassword&smsto=447974128549
	&smsfrom=1212&pushtype=0&push_href=
	http%3A%2F%2Fwww.mxtelecom.com%2F&push_action=2
	&push_siid=124&push_siexpires=
	2002-12-12&push_siname=Test+test

An example HTML form for this message type can be found here.

MMS Notification

Parameter	Description
mms_transaction_id	Identifies the notification and the subsequent transaction that is closed by the following M-NotifyResp.
mms_notification	1 - Flag as a MMS Notification
mms_version	1.0 - The MMS version number. According to this specification, the version is 1.0.
*mms_from	Address of the sender. This must be in the correct format. eg. Mobile Number: +447000123456/TYPE=PLMN or Email Address: Joe User <joe@user.org>
*mms_subject	Subject of the message.
mms_messageclass	Class of the message: 80 - Personal 81 - Advertisement 82 - Informational 83 - Auto
mms_messagelocation	This field defines the location of the message.
mms_expire	Length of time the message will be available (minutes).
mms_messagesize	Full size of message in bytes. The value of this header field could be based on approximate calculation,therefore it SHOULD NOT be used as a reason to reject the MMS.

The example below shows a typical HTTP request for an MMS Notification:

http://sms.mxtelecom.com/SMSSend?user=myusername&smsfrom=Test
	&pass=mypassword&smsto=447000123456
	&mms_notification=1
	&mms_version=1.0&mms_from=%2B447000123456%2FTYPE%3DPLMN&mms_transaction_id=123456
	&mms_subject=Test%20MMS&mms_messageclass=80
	&mms_messagelocation=http%3A%2F%2Fmmsc.mxtelecom.com%2F/123456
	&mms_expire=1440&mms_messagesize=35000

An example HTML form for this message type can be found here.

About MX Telecom MX Telecom is a leader in wireless technology. MX Telecom offers an easily accessible gateway to data, voice and video messaging services including 2-way and premium SMS, multimedia messaging, interactive voice response, location-based services, video short codes, Internet and TV related solutions. For more information, MX Telecom can be reached on 0845 666 7778, or via email at sales@mxtelecom.com.