Table Of Contents
Accessing SMS Gateway using SOAP:
Accessing SMS Gateway Using HTTP Get:
Accessing SMS Gateway using SMPP:
Language Specific instructions:
International Number Formatting
SMS Gateway is implemented using web services (Simple
Object Access Protocol over HTTP, port 80).
If you're not familiar with web services, click here for an
introduction and overview.
The URL for the web service (also know as the WSDL) is:
http://smsgateway.ca/SendSMS.asmx?WSDL
Method
The default method for sending messages is:
SendMessage(string CellNumber, string MessageBody, string AccountKey)
Parameters
The parameters to the SendMessage method are:
- CellNumber - The recipient cell phone number. In demo mode,
this will be ignored and all messages will be sent to your cell number. This parameter
is mandatory and cannot be empty.
- AccountKey - This is your unique account key which was emailed
to you when you created your account. This parameter is mandatory and cannot be
empty.
- MessageBody - This is the body of the message you want to send.
The maximum length of an SMS message is 160 characters. Messages greater than
160 characters will be broken up into multiple messages. This parameter is mandatory
and cannot be empty.
Return Value
The default Send methods return a single string which may have one of the following values:
On Success:
- Message queued successfully - Message was queued and will be sent
within the next few minutes.
Error Conditions:
- Cell number is invalid - The cell number was not supplied or was too
short. Cell numbers must be in the format "2125551212" or "212-555-1212". The area
code should be included, but not the leading "1".
- Message body was missing - No message was supplied. We do not permit
sending blank SMS messages.
- The account key parameter was not valid - The account key
was not supplied or or was less than 9 characters.
- This account is disabled - The specified account has been
disabled by our administrator for violating one or more of our policies.
- Account key not found - The specified account key cannot be found.
Please verify the key and try again.
- There are no messages remaining on this account - You will
need to purchase additional messages.
- No authorized credit plan found to match this phone number. Please check the
number, and ensure you are authorized to send messages to this region - By
default, all accounts are authorized to send to numbers located in Canada and the
United States only. Please contact us to find out how
to send to other regions.
- Message content is not acceptable, message not sent - Please
contact us for details.
There is method which allows you to tag your message with a "reference".
This will allow you to remember what the message was about at a later time. For
example, you might send the message "Call me right away", but it may be difficult
for your software to associate this message with the correct person/task/process. To assist you with this, you
might tag the message with the reference "job interview", or a client ID from your system. If someone
replies to your message, our email to you will contain this reference.
Please note that the SMS protocol only allows the reference to be associated with replies to
the most recently sent outbound message. References cannot be co-ordinated for multiple
conversations with the same mobile user at the same time.
SendMessageWithReference(string CellNumber, string MessageBody, string AccountKey,
string Reference)
In addition to the parameters required by the basic "SendMessage"
method, this method requires an additional parameter:
- Reference - This is used for your own "reference". If someone
replies to your message, the email we send to you will contain this reference so
you will be able to know what the message was about. This parameter is
mandatory, but it may be blank. If blank, the reference will be ignored and not
stored with the message (this is equivalent to using the SendMessage
method).
Our regular sending methods utilize 7-bit encoding in order to allow up to 160 characters in a
single message. The 7-bit character set does not include accented characters common in French
and Spanish. Thus, our regular sending methods "translate" accented characters into their
non-accented equivalents before sending (i.e. "é" becomes "e"). When it is essential that
your messages arrive with accents intact, we offer the SendUnicodeMessage method. It uses
16-bit encoding to permit Unicode characters, so the SMS size limitation restricts these
messages to 70 characters.
SendUnicodeMessage(string CellNumber, string MessageBody, string AccountKey,
string Reference)
The parameters for this method are identical to those for SendMessageWithReference.
However, keep in mind that we will split your MessageBody into 70 character chunks
and send those individually. Each 70 character chunk costs 1 message credit to send.
There are two additional send methods which
return "extended" information beyond just the success and error messages. These
methods return an
"SMSSendMessageResponse" object which has the following properties:
- MessagesRemaining (integer): The number of message credits remaining for
this account. This will
always be zero if there is an error retrieving the account information.
- ErrorMessage (string): A description of the error if applicable, otherwise blank.
- MessageID (integer): Unique value to identify this message. You can use
this value to reference a specific message if you request support from SMS
Gateway. This will allow us to tell which delivery network was used, the exact response
from the network, etc. Always zero if
there is an error.
- QueuedSuccessfully (boolean): True if queued
successfully, false if there was an error.
If false, check the ErrorMessage property.
The two methods which return this extended information are
SendMessageWithReferenceExtended and SendMessageExtended
SendMessageWithReferenceExtended(string CellNumber, string MessageBody, string AccountKey,
string Reference)
SendMessageExtended(string CellNumber, string MessageBody, string AccountKey)
The parameters are the same as those used in the basic "SendMessage" and "SendMessageWithReference" methods
There are two methods, SendMessageWithPriority
and SendMessageWithPriorityExtended which are
available for accounts which have been assigned to a
dedicated number. These methods will allow the user to change
the priority of the outgoing message. These methods will
have no effect if used by a client who does not have a
dedicated number. Please contact SMS Gateway for more
information about message priorities on dedicated numbers.
To send the same message to multiple phone
numbers, Professional and Enterprise level accounts may use the following method:
SendBulkMessage(string AccountKey, string MessageBody,
string Reference, string[] CellNumbers)
The parameters to the SendBulkMessage method are:
- CellNumbers - An array of recipient cell phone numbers. This parameter
is mandatory and cannot be empty. The maximum length of this array
is 5,000.
- AccountKey - This is your unique account key which was emailed
to you when you created your account. This parameter is mandatory and cannot be
empty.
- MessageBody - This is the body of the message you
want to send. Messages greater than
160 characters are not permitted when using this method. This parameter is mandatory
and cannot be empty.
- Reference - This is used for your own "reference".
If someone replies to your message, the email we send to you will
contain this reference so you will be able to know what the message was
about. This parameter is mandatory, but it may be blank. If blank, the
reference will be ignored and not stored with the message.
This method returns a string which will either confirm the
receipt of the message, or will describe the nature of the error.
To see how many outgoing message credits you have
remaining, you may use the following method:
GetRemainingMessageCount(string AccountKey)
The only parameter you must supply is your account key.
The message will return a string containing the count of
remaining credits. In the event of an error, it will
return the text, "Invalid Account Key"
To see the details and status of an outgoing message, you
may use the following method:
GetOutgoingMessage(int messageID, string accountKey)
This method returns an "SMSOutgoingMessage" object with
the following properties:
- CreditsDeducted (integer) - The number
of credits which were, or will be deducted from your
account upon successful sending of the message.
- Reference (string) - The
"reference" you supplied, if applicable.
- Sent (boolean) - True if sent,
false if the message is pending or was not sent due to
an error.
- QueueDate (datetime) - The date and time the
message was received by the web service and queued for
sending.
- MessageID (int) - A value which
uniquely identifies this message.
- SendDate (nullable datetime) - Null
if the message has not been sent, otherwise the date and time it
was sent.
- Status (string) - A value
indicating the status of the message. This can be "Pending",
"Success" or "Failed".
- Body (string) - The body or text of
the message.
- CellNumber (string) - The cell
number of the recipient.
The method accepts two parameters, the message ID and the
account key. In order to learn the message of ID of the
message at the time you send, you will need to use one of
the two "extended" send methods which contain the message ID
in the response. Alternatively, you can get the message ID
by requesting a list of recent outgoing messages using the
method below.
The method will return a "null" response under the
following conditions:
- If a user attempts to access a message sent by
another account. Only the sending account may get
information about the message.
- The account key does not exist.
- The message ID does not exist.
If you need to see a list of messages you've recently
sent, you may use the method:
GetSentMessages(string AccountKey, int MessageCount)
This method returns an array of "SMSOutgoingMessage"
objects which have the following properties:
- CreditsDeducted (integer) - The number
of credits which were or will be deducted from your
account upon successful sending of the message.
- Reference (string) - The
"reference" you supplied, if applicable.
- Sent (boolean) - True if sent,
false if the message is pending or was not sent due to
an error.
- QueueDate (datetime) - The date and time the
message was received by the web service and queued for
sending.
- MessageID (int) - A value which
uniquely identifies this message.
- SendDate (nullable datetime) - Null
if the message has not been sent, otherwise the date and time it
was sent.
- Status (string) - A value
indicating the status of the message. This can be "Pending",
"Success" or "Failed".
- Body (string) - The body or text of
the message.
- CellNumber (string) - The cell
number of the recipient.
This method accepts two parameters, the
account key and the number of message you wish to see. If you supply the number 50, for example,
you will get a list of the 50 most recently sent messages.
This method will return a "null" response if the account
key is invalid.
Use this method to see the most recent incoming messages
for your account:
GetIncomingMessages(string AccountKey, int
MessageCount)
This method returns an array of SMSIncomingMessage
objects which have the following properties:
- MessageNumber (int) - A value which
uniquely identifies this message. You can use this value
to help us identify a message if you should require
support from SMS Gateway.
- OutgoingMessageID (nullable int) -
If applicable, this is the unique ID of the outgoing
message which triggered a response.
- AccountKey (string) - The account
key of the incoming message recipient.
- Reference (string) - If we are able
to match this incoming message to an outgoing message
which triggered a response, this is the reference of
that
outgoing message.
- PhoneNumber (string) - The phone
number of the message sender.
- Message (string) - The text or body
of the incoming message.
- ReceivedDate (datetime) - The date
and time the message was received.
This method accepts two parameters, your account key
and the number of messages you wish to see. If you pass in
the value "50", for example, the method will return the 50
most recently received messages.
This method allows you to retrieve all the incoming
message you haven't already downloaded. In order to know
which messages to send, you must specify the number of the last
message you downloaded. This method will send all incoming
messages which have a message number greater than the number
you specify. The method to use is:
GetIncomingMessagesAfterID(string AccountKey,
int MessageNumber)
The method accepts two parameters, your account key and
the ID of the last message you retrieved. This method returns an array of SMSIncomingMessage
objects which have the following properties:
- MessageNumber (int) - A value which
uniquely identifies this message. You can use this value
to help us identify a message if you should require
support from SMS Gateway.
- OutgoingMessageID (nullable int) -
If applicable, this is the unique ID of the outgoing
message which triggered a response.
- AccountKey (string) - The account
key of the incoming message recipient.
- Reference (string) - If we are able
to match this incoming message to an outgoing message
which triggered a response, this is the reference of
that
outgoing message.
- PhoneNumber (string) - The phone
number of the message sender.
- Message (string) - The text or body
of the incoming message.
- ReceivedDate (datetime) - The date
and time the message was received.
This method allows you to see all incoming messages which
are a response to your outgoing message which contained the specified reference. The name of the method is:
GetIncomingMessagesByReference(string AccountKey,
int MessageCount, string Reference)
This method returns an array of SMSIncomingMessage
objects which have the following properties:
- MessageNumber (int) - A value which
uniquely identifies this message. You can use this value
to help us identify a message if you should require
support from SMS Gateway.
- OutgoingMessageID (nullable int) -
This is the unique ID of the outgoing
message which triggered a response.
- AccountKey (string) - The account
key of the incoming message recipient.
- Reference (string) - This is the reference
specified in the the outgoing message which triggered a
response.
- PhoneNumber (string) - The phone
number of the message sender.
- Message (string) - The text or body
of the incoming message.
- ReceivedDate (datetime) - The date
and time the message was received.
It is possible to send messages through SMS Gateway using a
simple HTTP Get request. The URL is:
http://smsgateway.ca/sendsms.aspx?CellNumber=XXX&MessageBody=XXX&AccountKey=XXX
When making the call, replace all three "XXX" values with the
parameters below:
Parameters
- CellNumber - The recipient cell phone number. In demo mode,
this will be ignored and all messages will be sent to your cell number. This parameter
is mandatory and cannot be empty.
- AccountKey - This is your unique account key which was emailed
to you when you created your account. This parameter is mandatory and cannot be
empty.
- MessageBody - This is the body of the message you want to send.
The maximum length of an SMS message is 160 characters. Messages greater than
160 characters will be broken up into multiple messages. This parameter is mandatory
and cannot be empty.
Return Value
The Send method returns a single string which may have one of the following values:
On Success:
- Message queued successfully - Message was queued and will be sent
within the next few minutes.
Error Conditions:
- Cell number is invalid - The cell number was not supplied or was too
short. Cell numbers must be in the format "2125551212" or "212-555-1212". The area
code should be included, but not the leading "1".
- Message body was missing - No message was supplied. We do not permit
sending blank SMS messages.
- The account key parameter was not valid - The account key
was not supplied or or was less than 9 characters.
- This account is disabled - The specified account has been
disabled by our administrator for violating one or more of our policies.
- Account key not found - The specified account key cannot be found.
Please verify the key and try again.
- There are no messages remaining on this account - You will
need to purchase additional messages.
- No authorized credit plan found to match this phone number. Please check the
number, and ensure you are authorized to send messages to this region - By
default, all account are authorized to send to numbers located in Canada and the
United States only. Please contact us to find out how
to send to other regions.
- Message content is not acceptable, message not sent - Please
contact us for details.
Using SOAP web services in the .Net framework is extremely simple. First, add a
web reference to your project which points to the above URL. All of the necessary
code for parsing messages and responses will be added to the project. Sending an
SMS message then consists of two lines of code: (assuming the required imports
or using statements are present)
SendSMS SMSMessenger = new SendSMS();
result = SMSMessenger.SendMessage(CellNumber, MessageBody, AccountKey);
Download Samples (.Net Framework 2.0, Visual Studio 2005)
PHP 5 SOAP Module Sample Code (Requires installation of the SOAP Module)
class SMSParam {
public $CellNumber;
public $AccountKey;
public $MessageBody;
}
$client = new SoapClient('http://www.smsgateway.ca/sendsms.asmx?WSDL');
$parameters = new SMSParam;
$parameters -> CellNumber = "212-555-1212";
$parameters -> AccountKey = "GSP1234567";
$parameters -> MessageBody = "This is a demonstration of SMSGateway.ca using PHP5.";
$Result = $client->SendMessage($parameters);
Download Samples
- PHP Samples - Includes samples using NuSoap
and the SOAP module in PHP 5. Please note that we do not recommend the NuSoap library for
our more advanced functions, as the handling of arrays in NuSoap is not compatible with
the latest SOAP standard.
We strongly recommend making using of the free Microsoft SOAP Toolkit. This toolkit contains a COM object
which allows you to make SOAP calls in three simple steps.
- First, create an instance of an MSSoap.SoapClient30 object.
- Initialize the instance by calling the mssoapinit method and passing in
the URL of the webservice.
- Call the SendMessage or SendMessageWithReference method on the
object.
Here is an example in Visual Basic 6:
Set SMSMessenger = CreateObject("MSSoap.SoapClient30")
Call SMSMessenger.mssoapinit("http://www.smsgateway.ca/SendSMS.asmx?wsdl")
Dim result As String
result = SMSMessenger.SendMessage(CellNumber, MessageBody,
AccountKey)
The SOAP Toolkit 3.0 can be downloaded here
Download Samples
Once your account has been authorized for sending outside of North America, you can text anywhere in the
world. Our service expects to be passed international phone numbers (in the CellNumber parameter) as digits only, starting with the country
code followed by the complete telephone number. Do not include a leading "011" or "+".
So for example, to text Australia (country code 61) your number should look like: 61455553333
Kenya (country code 254) would look like: 254755444333
|