Basic Send Operations Using SOAP and XML

 The URL for the WSDL is:

http://smsgateway.ca/SendSMS.asmx?WSDL

Basic Send 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 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, accounts are authorized to send to certain regions of the world 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.
• Time of day at destination falls outside the established time restrictions for your account, message not sent. - For Enterprise level accounts only - optional time-of-day windows can be created to restrict sending.

Multimedia (MMS) Send Operation using SOAP:

An MMS message is a multimedia message such as an image, video or audio file. If the recipient's phone supports MMS, this rich content will appear in line with other text messages.

For us to send MMS, the content must be hosted on the Internet and you must supply a URL to retrieve the content. If you have an image you want to send but it's not currently hosted on the Internet, we can host the image for you prior to sending. Click here for more details. Please confirm the validity of the content before sending. If the content cannot be downloaded, the recipient will not receive the message. We are unable to determine this upon sending and will still need to charge for the message.

MMS messages are charged at rate of three times the normal SMS rate for the destination. So, if a message to the recipient normally costs one credit, an MMS message to the same recipient will cost three message credits.

The method for sending MMS is:

SendMultimediaMessage(string CellNumber, string ContentURL, string AccountKey)

Parameters

The parameters to this 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.
• ContentURL - This is the URL of the content you wish to send.

Return Value

This 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, accounts are authorized to send to certain countries 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
• Time of day at destination falls outside the established time restrictions for your account, message not sent. - For Enterprise level accounts only - optional time-of-day windows can be created to restrict sending.
• Cannot send MMS outside Canada and US - At this time, we only support sending MMS to Canada and the United States. 

Advanced Operations using SOAP

Send a message with a Reference

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

Send Via Multiple Routes (useful for two factor authentication)

This operation will send your message twice using two mobile operators. Use this operation when your message is extremely critical and / or time sensitive. Using multiple routes will dramatically increase the chances that your message will be delivered quickly even in the unlikely event that a single mobile operator is experiencing delays. This sending operation is popular anytime you need to ensure the fastest possible critical delivery.

Please Note: Because your message is being sent twice, this operation costs twice the number of credits as our standard operation.

The operation to send via multiple routes is:

SendMessageMultiRoute(string CellNumber, string MessageBody, string AccountKey)

Send a message with Accented Characters

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.

Get Extended Response Information

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

Send Messages with a Designated Priority

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.

Send a Message from a Specific Dedicated Number

public string SendMessageViaDedicatedNumber(string CellNumber, string MessageBody, string AccountKey, string Reference, string SenderNumber)

This method requires one additional parameter, "SenderNumber" which is the phone number of your dedicated number that you wish to use to send the message.

Bulk Send Messages

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.  

Check Outgoing Message Credits

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"

Get the Status of an Outgoing Message

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:

1. If a user attempts to access a message sent by another account. Only the sending account may get information about the message.
2. The account key does not exist.
3. The message ID does not exist.

Get a List Of Recently Sent Outgoing Messages

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.  

Incoming Message Methods using SOAP

 Get Most Recent Incoming Messages

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.

Get New Incoming Messages

This method allows you to retrieve all the incoming messages 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.

Get Incoming Messages by Reference

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 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.