In order to utilise the SMSBroadcast API, users will first need to create API credentials in the web portal. Read this article for instructions on creating API keys in the web portal.
Once a new API key has been created, the API key and secret will need to be updated in the application with which the user wishes to use the API.
Introduction
The SMS Broadcast Advanced HTTP API can be used to integrate SMS messaging into your own systems. This API allows for tracking of SMS messages and includes functions for receiving inbound message replies.
1. Sending Data to the HTTP API
To use the API, you system needs to send a GET or POST request to our API URL.
The URL for the Advanced HTTP API is:
https://api.smsbroadcast.com.au/api-adv.php
or
http://api.smsbroadcast.com.au/api-adv.php
For security reasons, we recommend using the HTTPS protocol and POST your data to the API.
2. Sending SMS Messages
The send messages function can be used to send a single message or multiple messages in a single API request.
Input Parameters:
Parameter |
Description |
|
username |
This is the username for your API key |
|
password |
This is the password for your API key |
|
to |
The receiving mobile number(s). The numbers can be in the format:
We recommend using the international format, but your messages will be accepted in any of the above formats. To send the same message to multiple recipients, the numbers should be separated by a comma. The numbers should contain only numbers, with no spaces or other characters. |
|
from |
The sender ID for the messages. Can be a mobile number or letters, up to 11 characters and should not contain punctuation or spaces. Leave blank to use a number from the shared number pool. |
|
message |
The content of the SMS message. Must not be longer than 160 characters unless the maxsplit parameter is used. |
|
ref |
Your reference number for the message to help you track the message status. This parameter is optional and can be up to 20 characters. |
|
maxsplit |
Determines the maximum length of your SMS message (see details below) |
|
delay |
Number of minutes to delay the message. Use this to schedule messages for later delivery. |
Example API Request:
https://api.smsbroadcast.com.au/api-adv.php?username=myuser&password=mypass&to=0400111222,0400222333&from=MyCompany&message=Hello%20World&ref=112233&maxsplit=5&delay=15
The above request would send the message “Hello World” to 0400111222 and 0400222333 from MyCompany.
Input Parameters:
Parameter |
Description |
|
Status |
Will show if your messages have been accepted by the API. There are 3 possible results: |
|
Receiving Number |
The receiving mobile number. This will be shown in international format (614xxxxxxxx) regardless of the format it was submitted in. If you submit an invalid mobile number, the invalid number will be shown in the same format as it was submitted. |
|
SMS Reference Number or Error Message |
Will display our reference number for the SMS message, or the reason for a failed SMS message. |
The API will return 1 line of data for each SMS message you submit. The data is separated by the colon character.
Sample API Output:
The output from the previous example would be:
OK: 61400111222:2942263
OK: 61400222333:2942264
If you submit an invalid mobile number, the API would return:
BAD:0400abc111:Invalid Number
If you send multiple messages in the same request, the valid numbers will still be accepted by the API.
If you submit a request with a critical error (such as an incorrect username, password or missing a required parameter) the API will return only 1 line.
ERROR: Username or password is incorrect.
Long SMS Messages (maxsplit)
Standard SMS messages are limited to 160 characters, however our system allows you to send SMS messages up to 765 characters. This is achieved by splitting the message into parts. Each part is a normal SMS and is charged at the normal price. The SMS is then reconstructed by the receiving mobile phone and should display as a single SMS.
The maxsplit setting determines how many times you are willing to split the message. This allows you to control the maximum cost and length of each message. The default setting is 1 (160 characters). The maximum is 5 (765 characters).
If your SMS is 160 characters or less, it will be sent (and cost) as a single SMS, regardless of the value of this setting.
If your message is longer than 160 characters, it is split into parts of up to 153 characters (not 160).
3. Message Status Updates
Status updates allow you to keep track of the delivery of the messages you send. A confirmation will be sent to you to show if the message was successfully delivered or failed.
This option must be activated by SMS Broadcast. If you require this function, please contact us and provide us with the URL on your server to send the data.
The SMS Broadcast API will send a GET request to your URL (as provided when setup) with the below parameters.
Request Parameters
Parameter |
Description |
|
to |
The mobile number the message was sent to, in international format (614xxxxxxxx). |
|
ref |
Your reference number, if provided when you sent the message. |
|
smsref |
The SMS Broadcast reference number as returned by the API when the message was sent. |
|
status |
The current status of the message. Possible statuses are:
|
Example Request:
http://www.yourserver.com/status.php?to=61400111222&ref=112233&smsref=1122334455&status=Delivered
Each status request will contain the status of a single message, even if multiple messages were sent to the API in the same request.
The status information is provided by the mobile networks and may not be 100% reliable.
4. Inbound SMS Messages
Our API will send a request to your URL with the inbound SMS data for each message.
If you require this function, read this article for instructions on creating a webhook.
SMS Broadcast will send an HTTP GET request to the URL you provided when this service was activated.
Request Parameters
Parameter |
Description |
|
to |
The phone number the SMS was sent to. If you have multiple inbound numbers, you can use this to know which number the message was sentto. Will be shown in international format (614xxxxxxxx). |
|
from |
The mobile number that sent the message, in international format (614xxxxxxxx). |
|
message |
The content of the SMS message |
|
ref |
The reference number from the original outbound SMS, if provided |
Example Request:
http://www.yourserver.com/inbound.php?to=61400111222&from=61400111999&message=Hello%20World&ref=abc123
5. Account Balance
The account balance function can be used to lookup the number of credits left in your account.
Input Parameters
Parameter |
Description |
|
action |
This must be set to "balance" for this function |
|
username |
This is the username for your API key |
|
password |
This is the password for your API key |
Example Balance Request:
https://api.smsbroadcast.com.au/api-adv.php?action=balance&username=myuser&password=mypass
Output Parameters
Parameter |
Description |
|
Status |
Will show the status of your request. The possible statuses are: |
|
Balance or Error |
Will show your account balance or a reason for the error |
Sample API Output:
The output of a valid request will be similar to:
OK: 5000
The output of an invalid request will be similar to:
ERROR: Username or password is incorrect