How To Use SMS Gateway.ca

Basic Send Operation using REST and JSON:

The URL for the basic send operation is:

POST: http://smsgateway.ca/services/message.svc/{AccountKey}/{CellNumber}

Parameters

The parameters to this method are:

CellNumber - (Part of the request URL) 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 - (Part of the request URL) 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 - (Part of the request form data, formatted as JSON) 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.
Reference - (Optional, Part of the request form data, formatted as JSON) 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.

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

Note:

Your request should use the HTTP POST method (rather than GET), with your account key and cell number as part of the request URL as specified above. The message body should be sent as part of the form data, encoded in JSON. The content type of your request should be "application/JSON"

The form data you send, encoded in JSON, should look something like this:

{
"MessageBody": "Hello!",
"Reference": "My Reference!"
}

On success, the response you receive will look like this:

{
"SendMessageResult": "Message queued successfully"
}

Get Extended Response Information

There is an additional send method which returns "extended" information beyond just the success and error messages. This method returns 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 method which returns this extended information is:

POST: http://smsgateway.ca/services/message.svc/{AccountKey}/{CellNumber}/Extended

The parameters are the same as those used in the basic "Send" method - it requires a MessageBody as part of the form data, and you may optionally provide a "Reference".

The JSON response will look something like this:

{
   "SendMessageExtendedResult": {
       "ErrorMessage": "",
       "MessageID": 42476881,
       "MessagesRemaining": 482,
       "QueuedSuccessfully": true
   }
}

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 languages such as 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 two additional methods, one with simple result information, and one with extended result information (see above). They use 16-bit encoding to permit Unicode characters, so the SMS size limitation restricts these messages to 70 characters.

POST: http://smsgateway.ca/services/message.svc/{AccountKey}/{CellNumber}/Unicode

POST: http://smsgateway.ca/services/message.svc/{AccountKey}/{CellNumber}/UnicodeExtended

The parameters for these methods are identical to other send methods - you must specify the message body in the form data, and may optionally provide a reference.

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.

Send Messages With a Designated Priority

There are two methods which are available for accounts that have been assigned to a dedicated number. One moethod returns a simple response while the other returns exteded information. 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.

The parameters for these methods are identical to other send methods - you must specify the message body in the form data, and may optionally provide a reference. Specify the priority as the last part of the URL as indicated below.

http://smsgateway.ca/services/message.svc/{AcctKey}/{CellNumber}/Priority/{Priority}

http://smsgateway.ca/services/message.svc/{AcctKey}/{CellNum}/PriorityExtended/{Priority}

Bulk Send Messages

To send the same message to multiple phone numbers, Professional and Enterprise level accounts may use the following method:

POST: http://smsgateway.ca/services/message.svc/{AccountKey}/Bulk

The parameters to the SendBulkMessage method are:

CellNumbers - (Part of the form data in JSON) 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 - (Part of the request URL) 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 - (Part of the form data in JSON) 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 - (Part of the form data in JSON - optional). 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.

The form data you send, encoded in JSON, should look something like this:

{
    "MessageBody": "Hello!",
    "Reference": "My Reference!",
    "CellNumbers": ["7055551212","4165551212"]
}

On success, the response you receive will look like this:

{
"SendMessageResult": "2 messages queued successfully"
}

Get the Status of an Outgoing Message

To see the details and status of an outgoing message, you may use the following method:

GET: http://smsgateway.ca/services/message.svc/{AccountKey}/ID/{MessageId}

The method accepts two parameters, the message ID and the account key, both part of the URL. 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 one of the methods below.

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

The JSON will look something like this:

   {
      "Body": "Hello Mike",
      "CellNumber": "2125554970",
      "CreditsDeducted": 1,
      "FormattedQueuedDate": "10/10/2012",
      "FormattedQueuedTime": "1:53 PM",
      "QueueDate": "/Date(1349891617440-0400)/"
      "MessageID": 42489771,
      "QueueDate": "/Date(1341246335363-0400)/",
      "Reference": "",
      "SendDate": null,
      "Sent": false,
      "SuccessString": "Pending"
   }

Get a List Of Sent / Outgoing Messages

There are several ways to retrieve a list of sent messages. These include:

Most recent - Returns the most recent {Count} number of messages.

GET: http://smsgateway.ca/services/message.svc/{AccountKey}/count/{count}

By Reference - Returns all sent messages which have the given {Reference}

GET: http://smsgateway.ca/services/message.svc/{AccountKey}/reference/{Reference}

After a Given ID - Returns all message which have an ID greater than {MessageID}

GET: http://smsgateway.ca/services/message.svc/{AccountKey}/afterID/{MessageID}

By Reference After ID - Returns sent messages with the given {Ref}, and ID greater than {ID}

GET: http://smsgateway.ca/services/message.svc/{AccountKey}/referenceafterid/{ID}/{Ref}

All of these methods 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.

The JSON will look something like this:

[
   {
      "Body": "Hello Mike",
      "CellNumber": "2125554970",
      "CreditsDeducted": 1,
      "MessageID": 42489771,
      "QueueDate": "/Date(1341246335363-0400)/",
      "Reference": "",
      "SendDate": null,
      "Sent": false,
      "SuccessString": "Pending"
   },
   {
      "Body": "Hello John",
      "CellNumber": "2125554597",
      "CreditsDeducted": 1,
      "MessageID": 42489772,
      "QueueDate": "/Date(1341246335363-0400)/",
      "Reference": "",
      "SendDate": null,
      "Sent": false,
      "SuccessString": "Pending"
   }
]

Check Outgoing Message Credits

To see how many outgoing message credits you have remaining, you may use the following method:

GET: http://smsgateway.ca/services/account.svc/{AccountKey}/RemainingMessageCount

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 an error message.

Check Pending Message Count

To see how many pending messages you have in the queue, you may use the following method:

GET: http://smsgateway.ca/services/account.svc/{AccountKey}/PendingMessageCount

The only parameter you must supply is your account key. The message will return a string containing the count of pending messages. In the event of an error, it will return "-1"

Incoming Message Methods using SOAP

Get Most Recent Incoming Messages

Use this method to see the most recent incoming messages for your account:

GET: http://smsgateway.ca/services/incoming.svc/{AccountKey}/count/{MessageCount}

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

The resulting JSON will look something like this:

[
   {
       "AccountKey": GDE442Hvv2,
       "Message": "Info",
       "MessageNumber": 2591508,
       "OutgoingMessageID": 62566,
       "PhoneNumber": "15085556527",
       "ReceivedDate": "/Date(1341335593000-0400)/",
       "Reference": "Job Interview"
   },
   {
       "AccountKey": GDE442Hvv2,
       "Message": "Info",
       "MessageNumber": 2568135,
       "OutgoingMessageID": 62567,
       "PhoneNumber": "17015559776",
       "ReceivedDate": "/Date(1340751528000-0400)/",
       "Reference": "Job Interview"
   }
]

Get New Incoming 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 ID greater than the number you specify. The URL to use is:

GET: http://smsgateway.ca/services/incoming.svc/{AccountKey}/afterId/{Id}

This method returns an array of SMSIncomingMessage objects as described above.

To receive extended information about the incoming messages, you may call this method:

GET: http://smsgateway.ca/services/incoming.svc/{AccountKey}/afterIdExtended/{Id}

This method returns a "SMSIncomingMessageFull" object with a few more properties.

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 URL of the method is:

http://smsgateway.ca/services/incoming.svc/{AccountKey}/Reference/{Ref}/count/{Count}

This method accepts three 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.

To see only messages greater than a certain Id, you may use this method:

http://smsgateway.ca/services/incoming.svc/{AccountKey}/Reference/{Ref}/AfterId/{ID}