SMS API for Developers

Integrate SMS messaging into your business systems.
Our fully featured SMS API is simple yet powerful.

 

SMS API ALT1
Create, send and
view messages

SMS API ALT2View system
transactions

 

SMS API ALT3The API is designed to allow third party developers to access our system from an external source it can be accessed from most programming languages and as long as you are proficient in your language you should have no issues. We can provide an SDK in PHP with full documentation online.


SMS API Documentation

Our API allows you to build applications that can send SMS. Here’s how to get started.

Endpoint and format

Use the API by sending an HTTP POST to the following URL:

https://app.wholesalesms.com.au/api/v2/send-sms.json

You can also substitute .xml at the end of the URL if you prefer responses to be formatted in XML rather than JSON.

Authentication

You’ll need your API credentials to authenticate. You can find those on the Account Settings page.

Use the Basic authentication method, specifying your API key as the username, and API secret as the password. At the protocol level, this means joining the API key and secret with a colon (:), Base64 encoding it, and sending the resulting string in the HTTP Authorization header.

For example, if your API key is “xyz123” and API secret is “t0ps3cret“, you calculate the Base64 of “xyz123:t0ps3cret“. The resulting header is:

Authorization: Basic eHl6MTIzOnQwcHMzY3JldA==

Request parameters

Send your request as a regular application/x-www-form-urlencoded POST; this is the default in most instances. The body contains key–value pairs separated by equals signs, joined by ampersands. The keys and values should be escaped, replacing spaces with plus symbols, and URL encoding all other non-alphanumeric characters.

An overview of the parameters follows.

message required
The body of the SMS. An SMS message can be up to 925 characters; after the first 160 characters, each additional 153 characters will cost an additional credit per SMS.
to and/or list_id required
The destination for the SMS. At least one of to or list_id must be specified, or both.to takes a comma-separated list of phone numbers; they should be in international (E.164) format, although local numbers will work if in the correct format for the country specified in your Account Details.list_id expects the ID of a contact list, whose opted-in recipients will receive the message.
send_at
The time when the message should be sent. If omitted, the message is sent immediately. The time should be specified in the format YYYY-MM-DD HH:MM:SS or YYYY-MM-DD (implies midnight), and is interpreted as in UTC.
from
The Caller ID for the message. This can be up to 11 alphanumeric characters. If omitted, one of our system numbers will be used; this is required if you want recipients to be able to reply to the message, unless you have a dedicated number and specify it here.
dlr_callback
A URL for delivery callback reports. When a message is delivered, we’ll send a GET request to this URL. Details follow in the next section.
reply_callback
A URL for reply callbacks. When a message is replied to, we’ll send a GET request to this URL. See below.
validity
The maximum time we’ll attempt to deliver the message before giving up. Specify the number in minutes; 0 implies no limit.

Response

Assuming everything went well, you’ll receive an HTTP 200 response with JSON or XML body, depending on how you called the API. The body will have the following keys (or elements):

message_id
The ID of the message batch.
send_at
The time the message batch will be sent. The format is YYYY-MM-DD HH:MM:SS, and represents a date and time in UTC.
recipients
The number of recipients that will receive the message, including contact list contacts if list_id was specified.
cost
The cost to you in credits of sending this batch. This will depend on the number of recipients and length of message.
delivery_stats
An object describing statistics regarding the messages in the batch. The keys are delivered, pending, bounced, responses, and optouts. All keys will have zero values, except pending, which will equal the recipient count.
error
An object with two keys: code, which will have the value SUCCESS, and description. In case of error, a non-200 response will be returned, and this object can be used to find out what’s gone wrong.

Callbacks

When a message is delivered or replied to, we can notify a web service. We make a GET request to the URL of your choice, adding the query parameters detailed below. You can specify a URL with a query string, and we’ll simply append our parameters to those.

Delivery callbacks, sent to the URL specified in the dlr_callback parameter of the send-sms request, are generated whenever the delivery status of a message changes. We’ll add the following parameters to the URL:

message_id
The batch ID of the message. You can use this together with mobile to track delivery reports for the same message, and to correlate it with later replies.
mobile
The destination mobile number in E.164 format, with the leading plus symbol removed.
datetime
The date and time the delivery report was received. The format is YYYY-MM-DD HH:MM:SS.
status
The delivery status of the message. This will be one of pending (yet to be delivered), delivered (successfully delivered to the device), or hard-bounce (the message was rejected by the carrier; the destination number may not exist).

Reply callbacks, sent to the URL specified in the reply_callback parameter of the send-sms request, are generated when a reply to a message has been received. Note that the message must have been sent without a Caller ID specified (the from parameter), or with a number that correlates to a dedicated number you have in your account.

The following parameters are added to the URL for replies:

message_id
The batch ID of the message. This is the same ID that you will have earlier received delivery callbacks for, if you specified a URL for delivery callbacks.
mobile
The source mobile number in E.164 format, with the leading plus symbol removed.
datetime_entry
The date and time the reply was received. The format is YYYY-MM-DD HH:MM:SS.
response
The text of the message that was received.

Cancellations

If you schedule a message for future sending with send_at, you can cancel it up until 5 minutes before the scheduled sending time. Send a POST to the following URL:

https://app.wholesalesms.com.au/api/v2/cancel-sms.json

Send your request as above. This endpoint accepts only one endpoint: id. This is the same as the message_id returned by send-sms above.

Balance

You can get your current balance by sending a POST to the following URL:

https://app.wholesalesms.com.au/api/v2/get-balance.json

It takes no parameters. Your credit balance is returned in the balance key as a number.