Send SMS via SOAP API

Operation Name	Description
SoapSendSms	Use this operation to send a normal or flash SMS message
SoapSendBinarySms	Use this operation to send a binary SMS message. You must supply the correct UDH and DATA elements
SoapSendWapPush	Use this operation to send a WAP Push message. You must supply the WAP title and WAP URL
SoapSendMMSNot	Use this operation to send an MMS notification message

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.

The originator sets who the message appears to be from. This can be any MSISDN (up to 16 digits) or any alphanumeric string (up to 11 characters). If you supply an alphanumeric originator, it best to avoid using any symbols (non-A-Z 0-9 characters) to ensure maximum compatibility between different handsets. Please see the example code for a reference on how to use this element.

Type: xs:string

If you are not sure what type of handsets 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)

Optional: Yes

The message element contains that actual message you would like to send to the destinations.

Type: xs:string

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 which, when converted to the GSM character set, actually take up the space of two characters instead of one. 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 two characters instead of one:

‘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 entirely of the backslash character ‘\’, you would only be able to fit 80 of these per message.

Optional: No

The messagetype element is used to define what type of SMS message you would like to send. Use ‘text’ for a normal SMS or use ‘flash’ to send a flash message. Flash messages are SMS messages that are immediately displayed on the screen. They are also usually not saved in the inbox. Flash messages are usually handset dependant, so it would be advisable to send a test message to handset of the same type before sending any flash messages.

Type: xs:string
‘text’,
‘flash’

Optional: No

Type: xs:string

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 handsets 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)

Optional: Yes

This element is used to specify a title that is displayed on the destination handset

Type: xs:string

If you are not sure what type of handsets 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)

Optional: No

Type: xs:string

If you are not sure what type of handsets 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)

Optional: Yes

This element should contain the data part of the binary SMS.

Type: xs:hexBinary

If you are not sure what type of handsets 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)

Optional: No

The originator sets who the message appears to be from. This can be any MSISDN (up to 16 digits) or any alphanumeric string (up to 11 characters). If you supply an alphanumeric originator, it best to avoid using any symbols (non-A-Z 0-9 characters) to ensure maximum compatibility between different handsets. Please see the example code for a reference on how to use this element.

Type: xs:string

If you are not sure what type of handsets 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)

Optional: Yes

This is the subject for the notification message. It is what will be displayed in the inbox for example.

Type: xs:string

If you are not sure what type of handsets 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)

Optional: Yes

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 on how to send sms via soap using C#
*
* Copyright (c) 2007, aq Limited
* All rights reserved.
*/

using System;
using System.Drawing;
using System.Collections;
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;
using soapFunction.com.aql.gw1;
using System.Web.Services.Protocols;

namespace soapFunction
{
// Summary description for Form1.
public class Form1 : System.Windows.Forms.Form
{
private System.Windows.Forms.Button button1;
// Required designer variable.
private System.ComponentModel.Container components = null;
private SendSmsService cpLatestBrief = null;
public Form1()
{
// Required for Windows Form Designer support
InitializeComponent();
cpLatestBrief = new SendSmsService();
}

// Clean up any resources being used.
protected override void Dispose( bool disposing )
{
if( disposing )
{
if (components != null)
components.Dispose();
}
base.Dispose( disposing );
}

# region Windows Form Designer generated code
// Required method for Designer support - do not modify
// the contents of this method with the code editor.
private void InitializeComponent()
{
this.button1 = new System.Windows.Forms.Button();
this.SuspendLayout();

// button1
this.button1.Location = new System.Drawing.Point(80, 56);
this.button1.Name = "button1";
this.button1.Size = new System.Drawing.Size(104, 32);
this.button1.TabIndex = 0;
this.button1.Text = "button1";
this.button1.Click += new System.EventHandler(this.button1_Click);

// Form1
this.AutoScaleBaseSize = new System.Drawing.Size(5, 13);
this.ClientSize = new System.Drawing.Size(292, 266);
this.Controls.Add(this.button1);
this.Name = "Form1";
this.Text = "Form1";
this.ResumeLayout(false);
}

# endregion
/// The main entry point for the application.
[STAThread]
static void Main()
{
Application.Run(new Form1());
}
public void sendansms()
{

// Message details
string originator = "sender";
string message = "test message 1";
string [] destarr = new string[1];
destarr[0] = "447123456789"; // destination number

// create authentication object
cpLatestBrief.authValue = new auth();
cpLatestBrief.authValue.username = "username"; // your aql username
cpLatestBrief.authValue.password = "password"; // your aql password
string creditsused;
string outdesr;

System.DateTime dt = DateTime.Now;
com.aql.gw1.callbackelement cbe = new callbackelement();
cbe.callbackurl = "http://url.com";
cbe.callbacktype = com.aql.gw1.callbacktypeoptions.HTTPGET;

if (cpLatestBrief != null)
{
try
{
cpLatestBrief.SoapSendSms(destarr,originator,message,com.aql.gw1.mtype.text,"2",dt,false,cbe,out creditsused,out outdesr);
MessageBox.Show(creditsused, "Message sent, 1 credit is deducted",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
}
catch(SoapHeaderException e)
{
MessageBox.Show(e.Message, "Name Entry Error",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
}
catch(SoapException e)
{
System.Xml.XmlNode node = e.Detail;
string errorcode = e.Detail.FirstChild.InnerText;
string errortext = e.Detail.FirstChild.NextSibling.InnerText;
if(errorcode == "DESTERROR-INVALIDNUMBERS")
MessageBox.Show(e.Message, "Name Entry Error",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
else if(errorcode == "MESSAGE-NOTSUPPLIED")
MessageBox.Show(e.Message, "Name Entry Error",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
else
MessageBox.Show(errorcode+e.Message+" "+errortext, "Name Entry Error",MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
}
return;
}
else
return;
}
private void button1_Click(object sender, System.EventArgs e)
{
sendansms();
}
}
}

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 handsets 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)

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 two characters instead of one. 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 two characters instead of one:

‘This is a [string]’

If you have questions on this or any other subject, please raise a support query. Our staff will then respond to your query with an average response time of around 15 minutes.

Send SMS via SOAP API

Send SMS via SOAP API

Sending messages via the SOAP gateway

WSDL file

Operation specifications

SoapSendSms

Parameter: destinationarray

Parameter: originator

Parameter: message

Parameter: messagetype

Parameter: maxconcat

Parameter: sendtime

Parameters: dlrep

SoapSendWapPush

Parameter: destinationarray

Parameter: originator

Parameter: waptitle

Parameter: wapurl

Parameter: sendtime

dlrep

SoapSendBinarySms

Parameter: destinationarray

Parameter: originator

Parameter: data

Parameter: udh

Parameter: sendtime

Parameter: dlrep

Parameter: encoding

SoapSendMMSNot

Parameter: destinationarray

Parameter: originator

Parameter: subject

Parameter: mmsurl

Parameter: filesize

Parameter: class

Parameter: expiry

Parameter: sendtime

Parameter: dlrep

aql subtypes: callbackelement

Parameter: callbackurl

Parameter: callbacktype

Delivery Notification via HTTP

Sample code

Important considerations

Restricted strings

GSM character set

Download our Sales Brochure

Your browser is out-of-date!