HTTP Interface

API for sending and receiving text messages via the HTTP protocol

The SMS Gateway provides a HTTP and HTTPS interface to enable your applications to send and receive messages over the Internet. Message parameters are submitted in HTTP form fields, using either POST or GET method. Click on the Services below to see details of the required Form fields.

Send SMS Message

You can send SMS messages using the HTTP/S interface. Parameters are specified in the URL or as POST parameters:

http://www.intellisoftware.co.uk/smsgateway/sendmsg.aspx?username=MyUsername&password=MyPassword&to=44771012345,44771054321&text=The+Message

For secure SSL connection use https:

Parameters:

username= This is the username of your account
password= This is the password for your account
to= This is the destination phone number. A maximum of 100 numbers can be specified, separated by commas.
text= The content of the text message
from= (Optional) This is the source/sender's phone number
maxconcat= (Optional) Maximum number of concatenated SMS messages that will be sent per recipient (Default is 1)
type= (Optional) 1=Text, 6=Voice-SMS (Default is Text)

Responses:

ID:10011000000000000001 Message has been sent to the gateway. The unique message ID follows 'ID:'
ERR:LOGIN_INVALID Username or Password is invalid
ERR:INSUFFICIENT_CREDIT Insufficient credit balance to fulfil request
ERR:NO_XXXXXXXXXXX A mandatory parameter is missing
ERR:INVALID_NUMBER Unable to route to the destination phone number
ERR:INVALID_REQUEST The request was not valid
ERR:GATEWAY_ERROR Unable to process request at this time
ERR:INTERNAL_ERROR Unable to process request at this time

Response Formats:

Single line response is returned when sending to a single recipient or when the whole submission fails:

ID:10011000000000000001
ERR:INSUFFICIENT_CREDIT

Multiline response is returned when sending to multiple recipients:

44771012345,ID:10011000000000000001
44771012346,ID:10011000000000000001
44771054321,ERR:INVALID_NUMBER

A line is returned per recipient. Each line contains the recipient's number (international format), followed by comma, followed by the response. The ID applies to the whole submission and is identical for each recipient.

NOTE: The phone numbers listed in the response may not be identical to the numbers submitted. This is due to processing done to the numbers, e.g. international dialling codes added, duplicate numbers removed.

Send MMS Message

You can send MMS messages using the HTTP/S interface. The MMS message is submitted over the HTTP interface using the Multipart Form Data format.

Submission URL:

http://www.intellisoftware.co.uk/smsgateway/default.aspx

For secure SSL connection use https:

Request Data:

Request data contains submission parameters and the MMS message part files

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="username"
Content-Type: text/plain

YourUsername
--AaB03x
Content-Disposition: form-data; name="password"
Content-Type: text/plain

YourPassword
--AaB03x
Content-Disposition: form-data; name="to"
Content-Type: text/plain

0771012345
--AaB03x
Content-Disposition: form-data; name="from"
Content-Type: text/plain

0771054321
--AaB03x
Content-Disposition: form-data; name="type"
Content-Type: text/plain

5
--AaB03x
Content-Disposition: form-data; name="text"
Content-Type: text/plain

MMS Message Subject
--AaB03x
Content-Disposition: form-data; filename="file1.txt"
Content-Type: text/plain

... contents of file1.txt ...
--AaB03x
Content-Disposition: form-data; filename="file2.gif"
Content-Type: image/gif
Content-Transfer-Encoding: binary

...contents of file2.gif...
--AaB03x--

Parameters:

username= This is the username of your account
password= This is the password for your account
to= This is the destination phone number. A maximum of 100 numbers can be specified, separated by commas.
text= The content of the MMS message subject message (UTF-8 Encoded)
from= (Optional) This is the source/sender's phone number. Leave blank to receive replies. Can be numerical (e.g. long number or shortcode), alphanumeric sender's Id's not supported.
type= Message Type (5 = MMS Message)

Responses:

ID:10011000000000000001 Message has been sent to the gateway. The unique message ID follows 'ID:'
ERR:LOGIN_INVALID Username or Password is invalid
ERR:INSUFFICIENT_CREDIT Insufficient credit balance to fulfil request
ERR:NO_XXXXXXXXXXX A mandatory parameter is missing
ERR:INVALID_NUMBER Unable to route to the destination phone number
ERR:INVALID_REQUEST The request was not valid
ERR:GATEWAY_ERROR Unable to process request at this time
ERR:INTERNAL_ERROR Unable to process request at this time

Response Formats:

Single line response is returned when sending to a single recipient or when the whole submission fails:

ID:10011000000000000001
ERR:INSUFFICIENT_CREDIT

Multiline response is returned when sending to multiple recipients:

44771012345,ID:10011000000000000001
44771012346,ID:10011000000000000001
44771054321,ERR:INVALID_NUMBER

A line is returned per recipient. Each line contains the recipient's number (international format), followed by comma, followed by the response. The ID applies to the whole submission and is identical for each recipient.

NOTE: The phone numbers listed in the response may not be identical to the numbers submitted. This is due to processing done to the numbers, e.g. international dialling codes added, duplicate numbers removed.

Send Unicode Message

You can send Unicode SMS messages using the HTTP/S interface. The Unicode format is used to send multilingual messages not support by the standard GSM character set.

See Unicode Character Codes for more details.

The example below sends a Unicode message:

http://www.intellisoftware.co.uk/smsgateway/sendmsg.aspx?username=MyUsername&password=MyPassword&to=44771012345,44771054321&type=2&hex=00480045004C004C004F

For secure SSL connection use https:

Parameters:

username= This is the username of your account
password= This is the password for your account
to= This is the destination phone number. A maximum of 100 numbers can be specified, separated by commas.
type= Message Type (2 = Unicode)
hex= Unicode text encoded in hexadecimal (140 octets max, 70 unicode characters)
from= (Optional) This is the source/sender's phone number

Responses:

ID:10011000000000000001 Message has been sent to the gateway. The unique message ID follows 'ID:'
ERR:LOGIN_INVALID Username or Password is invalid
ERR:INSUFFICIENT_CREDIT Insufficient credit balance to fulfil request
ERR:NO_XXXXXXXXXXX A mandatory parameter is missing
ERR:INVALID_NUMBER Unable to route to the destination phone number
ERR:INVALID_REQUEST The request was not valid
ERR:PARAMETER_MISSING The mandatory 'hex' parameter is missing
ERR:PARAMETER_INVALID The 'hex' parameter are malformed
ERR:GATEWAY_ERROR Unable to process request at this time
ERR:INTERNAL_ERROR Unable to process request at this time

Send Binary Message

You can send a Binary SMS messages using the HTTP/S interface. The message can optionally include a User Data Header.

The example below sends a SmartMessage Logo:

http://www.intellisoftware.co.uk/smsgateway/sendmsg.aspx?username=MyUsername&password=MyPassword&to=44771012345,44771054321&type=3&udh=06050415820000&ud=32F40100480E01000000000000000000000000000000000000000000000000000000000001247803000000E0080120CC0640000040080120CC06C00000479E7124F0EFFADCF64448892479B6DAC6CD4448F9241DB6DACECF44488124CDB6CD96CC44488924CDB6CD96CDE446712478E66D9EC6000000000000000000000000000000000000

For secure SSL connection use https:

Parameters:

username= This is the username of your account
password= This is the password for your account
to= This is the destination phone number. A maximum of 100 numbers can be specified, separated by commas.
type= Message Type (3 = Binary)
udh= (Optional) User Data Header
ud= User Data (140 octets max)
from= (Optional) This is the source/sender's phone number

Responses:

ID:10011000000000000001 Message has been sent to the gateway. The unique message ID follows 'ID:'
ERR:LOGIN_INVALID Username or Password is invalid
ERR:INSUFFICIENT_CREDIT Insufficient credit balance to fulfil request
ERR:NO_XXXXXXXXXXX A mandatory parameter is missing
ERR:INVALID_NUMBER Unable to route to the destination phone number
ERR:INVALID_REQUEST The request was not valid
ERR:PARAMETER_MISSING The mandatory 'ud' parameter is missing
ERR:PARAMETER_INVALID The 'ud' or 'udh' are malformed
ERR:GATEWAY_ERROR Unable to process request at this time
ERR:INTERNAL_ERROR Unable to process request at this time

Send WAP PUSH Message

You can send a WAP PUSH message using the HTTP/S interface. WAP PUSH messages can send multimedia content, such as an Image, Wallpaper, Ringtone or a link to WAP website.

The example below sends a link to an image:

http://www.intellisoftware.co.uk/smsgateway/sendmsg.aspx?username=MyUsername&password=MyPassword&to=44771012345,44771054321&type=4&text=The+message+text&href=http://www.intellisoftware.co.uk/images/IntelliSMS.gif

For secure SSL connection use https:

Parameters:

username= This is the username of your account
password= This is the password for your account
to= This is the destination phone number. A maximum of 100 numbers can be specified, separated by commas.
type= Message Type (4 = WAP PUSH)
text= Display Text for WAP PUSH message
href= URL link to resource ( should start with 'http://' or 'https://' )
from= (Optional) This is the source/sender's phone number

Responses:

ID:10011000000000000001 Message has been sent to the gateway. The unique message ID follows 'ID:'
ERR:LOGIN_INVALID Username or Password is invalid
ERR:INSUFFICIENT_CREDIT Insufficient credit balance to fulfil request
ERR:NO_XXXXXXXXXXX A mandatory parameter is missing
ERR:INVALID_NUMBER Unable to route to the destination phone number
ERR:INVALID_REQUEST The request was not valid. Check sizes of text and href parameters, see note below.
ERR:PARAMETER_MISSING The mandatory 'href' parameter is missing
ERR:GATEWAY_ERROR Unable to process request at this time
ERR:INTERNAL_ERROR Unable to process request at this time

Considerations:

Our gateway will only send one SMS message per submission. Therefore a WAP PUSH message is charged at 1 credit.

An INVALID_REQUEST will result if the submitted text and href parameters would require 2 SMS messages to be sent. As a guide, the href and text parameters combined should not exceed 114 characters (assuming href starts with 'http://www.' )

Get Balance

You can obtain your current balance via the HTTP interface as follows:

http://www.intellisoftware.co.uk/smsgateway/getbalance.aspx?username=MyUsername&password=MyPassword

Parameters:

username= This is the username of your account
password= This is the password for your account

Responses:

BALANCE:100 The number of remaining credits follows 'BALANCE:'
ERR:LOGIN_INVALID Username or Password is invalid
ERR:NO_XXXXXXXXXXX A mandatory parameter is missing
ERR:INTERNAL_ERROR Unable to process request at this time


Retrieve MMS Message

You can retrieve an MMS Message part via the HTTP interface as follows:

http://www.intellisoftware.co.uk/smsgateway/retrievemms.aspx?username=MyUsername&password=MyPassword&msgid=500110000000001&msgpart=cid1.gif

Parameters:

username= This is the username of your account
password= This is the password for your account
msgid= Unique message id
msgpart= Filename or Index (1 based) of required MMS Message part


Responses:

ERR:LOGIN_INVALID Username or Password is invalid
ERR:MSGID_INVALID Message id does not match a received MMS message
ERR:NO_USERNAME The username parameter is missing
ERR:NO_PASSWORD The password parameter is missing
ERR:NO_MSGID The msgid parameter is missing
ERR:PARAMETER_MISSING The msgpart parameter is missing
ERR:PARAMETER_INVALID A parameter is invalid
ERR:GATEWAY_ERROR Unable to process request at this time
ERR:INTERNAL_ERROR Unable to process request at this time

Update Subscription List

Use this interface to update, remove and add entries to Subscription List. For more information about Subscription Lists please click here.

http://www.intellisoftware.co.uk/smsgateway/updatesubscriptionlist.aspx?username=MyUsername&password=MyPassword&sublistname=MySubscriptionListName&msisdn=44771012345&action=1

For secure SSL connection use https:

Parameters:

username= This is the username of your account
password= This is the password for your account
sublistname= This is the name of the subscription list
msisdn= This is the phone number to be updated
action= Action to be performed
1 = Subscribe phone number (Opt-in)
2 = Unsubscribe phone number (Opt-out)
3 = Delete phone number from subscription list

Responses:

OK The request action has been completed
ERR:LOGIN_INVALID Username or Password is invalid
ERR:NO_USERNAME Username parameter is missing
ERR:NO_PASSWORD Password parameter is missing
ERR:PARAMETER_MISSING sublistname, msisdn or action parameter is missing
ERR:PPARAMETER_INVALID sublistname or action parameter is invalid
ERR:INVALID_REQUEST The request was not valid
ERR:GATEWAY_ERROR Unable to process request at this time
ERR:INTERNAL_ERROR Unable to process request at this time

Receive SMS Message

Our server can be configured to forward received SMS messages to you webserver via a HTTP POST.

To configure HTTP forwarding please login into your account and go to Preferences and then select the Forwarding tab.

POST Fields:

from The mobile number of the message sender.
text The content of the text message
msgid IntelliSoftware's allocated message id
sent Date and time message was sent (in W3CDTF DateTime Format)
Examples:
2010-02-03T13:50:05-00:00 = 3rd Feburary 2010 13:50:05 GMT
2010-06-10T14:45:12+01:00 = 10th June 2010 14:45:12 BST
networkcode The sender's home network.
This parameter is only available for messages received on shortcodes. See Network Code table for values.

HTTP Response:

Our server expects a HTTP 200 (OK) status. Any content returned by your server will be ignored.

If anything other than a status 200 is returned then our server will consider this an error. On an error condition our server will retry to delivery the same message every 5 minute until the error is resolved.

ASP Example:

<%
From = Request("from")
Text = Request("text")

-- Place code here to use From and Text values
-- e.g. store message to a database

%>

Message Status Report

Our server can be configured to forward message status reports (e.g. Delivery Reports) to you webserver via a HTTP POST.

To configure HTTP forwarding please login into your account and go to Preferences and then select the Forwarding tab.

POST Fields:

msgid Unique message id (as returned when message was sent)
status

The message status:
0 - Unknown
1 - OK
2 - Message Queued
3 - Message Sent
4 - Message Delivered
5 - Error With Request
6 - Unable To Deliver
7 - Routing Error
8 - Message Expired
11 - Acknowledged By Recipient (Voice-SMS Only)
12 - Rejected By Recipient (Voice-SMS Only)

toaddr Phone Number message was sent to

HTTP Response:

Our server expects a HTTP 200 (OK) status. Any content returned by your server will be ignored.

If anything other than a status 200 is returned then our server will consider this an error. On an error condition our server will retry to delivery the same status report every 5 minute until the error is resolved.

ASP Example:

<%
MsgId = Request("msgid")
Status = Request("status")
ToAddr = Request("toaddr")

-- Place code here to use MsgId, Status and ToAddr values
-- e.g. store status report to a database

%>

Receive MMS Message

Our server can be configured to forward received MMS messages to you webserver via a HTTP POST.

To configure HTTP forwarding please login into your account and go to Preferences and then select the Forwarding tab.

POST Fields:

from The mobile number of the message sender.
text The MMS message's Subject field
msgid The message id, this is required to retrieve the MMS message contents
type The message type:
1 - SMS Text message
5 - MMS Message
filelist Comma separated list of component filenames

HTTP Response:

Our server expects a HTTP 200 (OK) status. Any content returned by your server will be ignored.

If anything other than a status 200 is returned then our server will consider this an error. On an error condition our server will retry to delivery the same message every 5 minute until the error is resolved.

ASP Example:

<%
From     = Request("from")
Text     = Request("text")
MsgId    = Request("msgid")
Type     = Request("type")
FileList = Request("filelist")

-- Place code here to use values
-- e.g. store message to a database

%>

Subscription List Event

Our server can be configured to send notifications of changes to Subscription Lists. For more information about Subscription Lists please click here.

To configure Subscription Lists Event notifications, please login into your account and go to Preferences and then select the Forwarding tab.

POST Fields:

sublistname Subscription list name.
sublisttype Subscription List Type:
1 = Premium Rate Subscription List (ARB)
2 = User Subscription List (Setup in SMSWeb)
msisdn Mobile phone number that has been updated within the Subscription List
action Action that was performed:
1 = Subscribed phone number (Opt-in)
2 = Unsubscribed phone number (Opt-out)
3 = Deleted phone number from subscription list
source The source of the change:
1 = Inbound SMS Message (MO)
2 = Inbound MMS Message (MO)
3 = Outgoing SMS Message (MT)
4 = Outgoing MMS Message (MT)
5 = Web Portal (WebSMS)
6 = Change made by IntelliSoftware Support
7 = Change made via API
8 = Platform Level Event (e.g. STOP to 86688)
9 = Message Delivery Status Report
10 = IntelliSoftware Help Desk (via Phone Call)
11 = IntelliSoftware Help Desk (via Email)
12 = IntelliSoftware Help Desk (via Web Form)
timestamp Date and time change was made (in W3CDTF DateTime Format)
Examples:
2010-02-03T13:50:05-00:00 = 3rd Feburary 2010 13:50:05 GMT
2010-06-10T14:45:12+01:00 = 10th June 2010 14:45:12 BST

HTTP Response:

Our server expects a HTTP 200 (OK) status. Any content returned by your server will be ignored.

If anything other than a status 200 is returned, then our server will consider this an error. On receipt of an error our server will retry to deliver the same message every 5 minutes until the error is resolved.

ASP Example:

<%
SubscriptionListName = Request("sublistname")
PhoneNumber = Request("msisdn")
Action = Request("action")


-- Place code here to use SubscriptionListName, PhoneNumber
-- and Action values
-- e.g. store notification to a database

%>

Network Codes

Here is a list of network codes returned by the IntelliSoftware SMS platform:

234010 O2 (UK)
234015 Vodafone (UK)
234020 Three (UK)
234030 T-Mobile (UK)
234033 Orange (UK)
0 Network Unknown

Advanced Features

Send to Distribution Lists (or Group Send)

Our gateway allows you to send SMS messages to preconfigured Distribution Lists or Groups. To send to a Distribution List or Group simply insert the Group Name were you would normally place the recipient's phone number. Distribution Lists or Groups are setup in your online account login on the Contacts page.

Reply Tracking:

The IntelliSoftware platform provides tracking of SMS replies, allowing you to determine which particular message a mobile user is replying to. When you submit a message to the SMS Gateway you can supply a User Context parameter. When a reply is received, the IntelliSoftware platform will included the User Context parameter when forwarding the message to your server.

The User Context can be supplied to the IntelliSoftware platform in the following ways:

.Net Component use SendMsgWithUserContext method
COM Component use SendMessageWithUserContext method
HTTP Interface add 'usercontext' POST/GET parameter
SMTP Interface (Email to SMS) add 'UserContext:' parameter
PHP SDK use SendMessageWithUserContext method
Java SDK use SendMessageWithUserContext method

The IntelliSoftware platform will forward the User Context for received messages in the following ways:

HTTP Interface 'usercontext' POST/GET parameter
SMTP Interface (SMS to Email) User Context appears in Subject line

Resilient Service:

For resilience, we run a backup gateway at www.intellisoftware2.co.uk that should be used if the primary gateway fails. You should provide functionality in your code that will switch to the backup gateway should the primary gateway fail. This functionality is already incorporated in the IntelliSMS COM and DotNet Components.