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