Text us or call us on : 011 33 20 30 40

SOAP API

Sending messages via the SOAP Gateway


You can seamlessly integrate your applications with aqls outbound sms messaging service via SOAP. 


WSDL file

In order to create your proxy classes we have provided a WSDL file. This can be located at the following URL

http://gw.aql.com/soap/sendservice.php?WSDL


There are 4 operations permitted within the SendSmsService service (as defined in the wsdl file above). These are:

Operation Name Description
SoapSendSms

Use this operation to send a normal or flash SMS message. Further details on this operation can be found here

SoapSendBinarySms

Use this operation to send a binary SMS message. You must supply the correct UDH and DATA elements. Further details on this operation can be found here

SoapSendWapPush

Use this operation to send a Wap Push message. You must supply the Wap title and Wap URL. Further details on this operation can be found here

SoapSendMMSNot

Use this operation to send an MMS notification message. Further details on this operation can be found here



Operation Specifications

This section gives a description of each of the operations listed in the table above. This includes the various element names, their type, list of possible values (if applicable e.g a restricted type), if it is optional and examples of the elements use.

For any elements that have restricted types (i.e they can only have certain values), the permitted values will be listed in single quotes. An example of this is the messagetype element in the SoapSendSms operation.

All types prefixed with xs: are from the http://www.w3.org/2001/XMLSchema namespace. Information on the types available within the namespace can be found here

SoapSendSms

Parameter Type possible values Optional Example
destinationarray Array of number elements any valid MSISDN No See code
originator xs:string Restricted
Strings
Yes See code
message xs:string GSM Char Set No See code
messagetype xs:string 'text',
'flash'
No See code
maxconcat xs:integer 1-255 Yes See code
sendtime xs:dateTime any valid date Yes See code
dlrep callbackelement see callback type Yes See code


SoapSendBinarySms

Parameter Type possible values Optional Example
destinationarray Array of number elements any valid MSISDN No See code
originator xs:string Restricted
Strings
Yes See code
data xs:hexBinary 0-9A-Z No See code
udh xs:hexBinary 0-9A-Z No See code
sendtime xs:dateTime any valid date Yes See code
dlrep callbackelement see callback type Yes See code
encoding xs:integer '7',
'8',
'16'
Yes
(default 8)
See code


SoapSendWapPush

Parameter Type possible values Optional Example
destinationarray Array of number elements any valid MSISDN No See code
originator xs:string Restricted
Strings
Yes See code
waptitle xs:string Restricted
Strings
No See code
wapurl xs:string any valid URL No See code
sendtime xs:dateTime any valid date Yes See code
dlrep callbackelement see callback type Yes See code


SoapSendMMSNot

Parameter Type possible values Optional Example
destinationarray Array of number elements any valid MSISDN No See code
originator xs:string Restricted
Strings
Yes See code
subject xs:string Restricted
Strings
No See code
mmsurl xs:string any valid URL No See code
filesize xs:integer Positive integer No See code
class xs:integer '80',
'81',
'82',
'83'
No See code
expiry xs:integer Positive integer. (Days) No See code
sendtime xs:dateTime any valid date Yes See code
dlrep callbackelement see callback type Yes See code

aql Subtypes

callback type

The callbackelement type (which the dlrep is a type of) consists of 2 subelements. These are the type of callback and the callback URL:

callbackelement

Parameter Type possible values Optional Example
callbackurl xs:string any valid URL No See code
callbacktype xs:string 'HTTPGET',
'NONE'
No See code

Delivery Notification via HTTP

An example of a callback url is:

http://yourdomain.com/yourscript.php?reportcode=%code&destinationnumber=%dest&myreference=123

You must provide the '%code' and the '%dest' literals in your callback URL because these are replaced with the destination number and the resultcode.

The resultcode determines the status of the message at that particular time. The possible values of this callback are:

1 = Delivered to Handset
2 = Rejected from Handset
4 = Buffered in transit (phone probably off / out of reception)
8 = Accepted by SMSC
16 = Rejected by SMSC

You can set any other variables in the callback for your own tracking; for example myreference in this case.

NOTE: If the message you send has to be split into multiple parts (e.g a wap push or a concatenated message), you will receive a delivery notification for each part.

Sample Code



For sample code on how to use our SOAP interface in ASP.NET - C# (C Sharp): SMS SOAP Sample Code.

Note: You would need to compile the SOAP library from the wsdl.

Important considerations



Restricted strings

When sending SMS messages, we recommend that certain strings have restrictions placed upon them. This includes the originator, the Wap Title in a wap push message and the subject in an MMS notification. This is to ensure maximum compatibility between different handsets. Our gateway does not enforce any of these restrictions, as there are handsets that can accept messages with characters from the whole character set.

If you are not sure what type of hand sets you are messaging to or if they can handle the full character sets in these fields, you are probably best to restrict the characters to the following:

A-Z, a-z, 0-9, - (hyphen), _ (underscore)


GSM Character Set

When a normal SMS message is sent to a handset, it is always converted into the GSM character set. There are certain characters, when converted to the GSM character set, actually take up the space of 2 characters instead of 1. These characters are:

^, {, }, \, [, ], ~, |,
0x0C (Form feed in ASCII),
0x80 (Euro char in GSM. Non-graphic char in ISO-8859-1)

This is best illustrated by an example. The following string takes up 16 characters (excluding the quotes):
        'This is a string'

The following string now takes up 20 GSM characters as the brackets each take up 2 characters instead of 1:
        'This is a [string]'

The number of characters that are allowed in each message are 160. The GSM character set issue basically means that this limit could be reduced to 159 or less depending on how many of the extended characters you place within your message. I.e, if your messages were to consist entiely of the backslash character '\', you would only be able to fit 80 of these per message.

If you have questions on this or any other subject, please raise a support query by logging into your account and going here. Our Staff will then respond to your query with an average response time of around 15 minutes.