HTTPS API
Overview
This page describes the resources that make up the Mobile Gateway HTTPS API v2, for developers who want to integrate an SMS Gateway into their application.
The Mobile Gateway HTTPS API provides access to send messages to handsets. To use the HTTPS API, your application will make an HTTPS request and parse the response. The response format is text/plain. You will utilise HTTP GET requests over TLS (https).
Authentication
All authentication is done using query parameters within the HTTPS GET request. If you do not provide the correct credentials in the URI when accessing the API, you will get a HTTP 401 response (HTTP 500 with version 1) with the text “ERROR Invalid authentication information” in the body.
You can change you password and find out the authentication parameters values at https://sms.optus.com.au/gateway/api_config/http. If you are unable to access this or have any other issues, please contact optussd@modicagroup.com.
Authorised IP Addresses
You can whitelist your servers’ IPs or IP ranges using the ‘Add IP Address’ button under “Authorised IP Addresses”
Please note: once one or more IP addresses or IP ranges have been added connections from all other IP addresses will be rejected, any attempt from an IP not in the list will receive an Authentication error.
Base URI
All API access is HTTP over TLS (https), from:
https://api.sms.optus.com.au/message
Versions
The HTTPS API version is currently v2. The only difference between v1 and v2 is that v2 provides new HTTP response codes. We recommend customers utilise the REST API if you require a more advanced API.
Error Codes
The HTTP response that the gateway returns on errors will depend on the API version you request. The following errors can occur:
| Code | Description | v1 Response code | v2 Response code |
|---|---|---|---|
Invalid authentication information |
The application or password parameters are missing or incorrect | 500 | 401 |
Missing <parameter name> parameter |
The parameter named is missing or the gateway is unable to identify it | 500 | 400 |
Failed to queue message |
The gateway was unable to create the message. The most likely cause for this is that the destination number was not valid or the mobile network for that number hasn’t been setup on your account. | 500 | 400 |
<message id> |
The message was submitted successfully | 200 | 200 |
Sending an SMS Message
To send an MT message to a mobile handset, submit a GET request:
GET /message?application=example_app&password=example_pass&class=example_class&content=example+content&destination=%2b642100000&version=2 HTTP/1.1
Host: api.sms.optus.com.au
The bold parameters are required, italic parameters are optional.
| Parameter | Required | Description |
|---|---|---|
| application | Yes | The application name provided by Modica. |
| password | Yes | The password for the named application as provided by Modica. |
| content | Yes | The text to be sent verbatim to the mobile phone. |
| destination | Yes | The mobile phone number the message is to be delivered to. Number format must be international format e.g. +64211234567 / +61414123456 / +18123456789. International format usually means removing the leading zero (from local numbers) and replacing with the country code preceded by a plus ( + ). The plus + sign will need to be URL encoded correctly in the API call: eg destination=%2B180923456789 |
| class | Yes (Only if using a mask) | Allows you to define the type of message. Classes are used to determine how to route and bill the message, as well as provide useful reporting information. Modica will supply you with set of valid classes available to your account. In most cases this should be mt_message. If the source parameter is used then class must not be included. |
| source | No | Allows you to select the source short code or mobile number where you have multiple available. This parameter is optional but when it is used it must be used instead of the class parameter. |
| mask | No | If you have a requirement for your SMS message to appear to come from something other than the MSISDN or shortcode you have been provisioned with, you can use the mask parameter to set this. NOTE: If you use a mask not configured in the list of available masks, the mask will be ignored, and the message will arrive from the source address of the application (e.g. shortcode). Masks are case sensitive. |
| reference | No | Free form text field for your reference which may aid in reporting. This field is optional and can contain up to 50 characters. If supplied, subsequent status callbacks for your message will include this data. |
| expires | No | RFC3339 formatted timestamp for the expiry time of the message, eg 2017-05-05T10:00:00+12:00. If this time is reached and the message has still not reached the mobile phone, then it is expired and not sent. Note this may not work for all mobile carriers. |
| version | No | If this is set to 2 the gateway will provide better HTTP response codes. Default is 1. |
On success:
HTTP/1.1 200 OK
<message-id>
On error:
HTTP/1.1 400
ERROR <error description>
MO Callback
If an MO Callback URL has been supplied at: https://sms.optus.com.au/gateway/api_config/http, messages from handsets will be supplied to your URL.
We recommend using https:// for your callback URLs.
If you supplied an MO callback URL of:
https://your-server.example.com/receiveMessage,
you will then receive a GET request like:
GET /receiveMessage?id=12345&source=%2B642741234567&destination=4433&content=Message+content+here&operator=Telecom_NZ HTTP/1.1
Host: your-server.example.com
The request will contain the following GET parameters:
| Parameter | Description |
|---|---|
| id | The gateway message ID. All message IDs will be returned as 64bit Signed Integers |
| source | The mobile number of the sender (including the leading + and country code) |
| destination | The destination short code or MSISDN |
| content | The message content |
| reply_to | The ID of the message this message is in reply to (only when a number sequence is used, and the MO is in reply to an MT message) |
| operator | The Operator (mobile carrier) name that the message was sent from |
If the message from the handset contains binary content, one additional parameter will be supplied:
| Parameter | Description |
|---|---|
| encoding | The value “base64” will be supplied for messages containing binary data. Content will be supplied encoded using base64, decoding content is needed to obtain the original data. NOTE: Regular SMS messages with GSM 7-bit or Unicode content will not supply this parameter. |
If the message contains a reply_to and the MT message had a reference provided, then an additional parameter will be added:
| Parameter | Description |
|---|---|
| reference | Your free-form text field supplied when creating the MT message, maximum of 50 characters. |
DLR Callback
If a DLR Callback URL has been supplied at: https://sms.optus.com.au/gateway/api_config/http, delivery receipts will be supplied to your URL.
We recommend using https:// for your callback URLs.
If you supplied a DLR callback URL of:
https://your-server.example.com/receiveStatus,
you will then receive a GET request like:
GET /receiveStatus?id=54321&status=received HTTP/1.1
Host: your-server.example.com
The request will contain the following GET parameters:
| Parameter | Description |
|---|---|
| id | The gateway message ID. All message IDs will be returned as 64bit Signed Integers |
| status | The status text of the message |
If a reference field was supplied when creating the message, one additional parameter will be provided:
| Parameter | Description |
|---|---|
| reference | Your free-form text field supplied when creating the message, maximum of 50 characters. |
Possible statuses vary between carriers, for instance some carriers will mark a message as ‘rejected’ when the mobile number is invalid, the phone has insufficient credit or the message has been expired. Other carriers will differentiate between each of these events.
You will need to cater for the following statuses:
| Status | Description |
|---|---|
| failed | Message delivery has failed due to carrier connectivity issue |
| sent | Message has been sent by the carrier transport |
| frozen | A transient error has frozen this message |
| dead | Killed by administrator |
| received | Message has been received by the handset |
| submitted | Message successfully submitted to the carrier for delivery |
| rejected | The carrier rejected the message |
| expired | The carrier was unable to deliver the message in a specified amount of time. For instance when the phone was turned off. |
Help
Having trouble integrating with any of our services? Visit our helpdesk at https://sms.optus.com.au/docs/ or contact optussd@modicagroup.com and we’ll help you sort it out.
