Affiliate Login
Learn More Try it How to use Pricing Login

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"
}

 

Multimedia (MMS) Send Operation using REST and JSON:

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 URL for the basic send operation is:

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

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.
  • URLOfContent - (Part of the request form data, formatted as JSON) 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. 

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 content URL 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:

{
    "URLOfContent": "http://smsgateway.ca/images/logo.jpg",
}
On success, the response you receive will look like this:
{
    "SendMultimediaMessageResult": "Message queued successfully"
}

 

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:

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

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". This method will return a "SendMessageMultiResult" object with either the string "Message queued successfully" or an error message if the message could not be sent.

 

 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 from a Specific Dedicated Number

Note: This operation only applies to customers who have more than one dedicated number. For all other customers, using this method will return an error. Use this method to specify which of your multiple dedicated numbers you wish to use to send a message. The URL is as follows:
POST: http://smsgateway.ca/services/message.svc/{AccountKey}/{CellNumber}/ViaDedicated

This method requires one additional parameter in the body, "SenderNumber" which is the phone number of your dedicated number that you wish to use to send the message. The body of your request will look something like this

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

 

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

Unlike other operations, messages you send using this operation must be less than 160 characters. Messages longer than this will not be split into smaller messages. Instead, an error message will result.

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:

  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.
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 REST and JSON

 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}

 

footer
© 2015 Swift SMS Gateway Inc.