REST v2

Overview

Our Mobile Gateway RESTv2 API allows you to send SMS messages.

The difference between REST and RESTv2, is a more modern approach, designed for scale and asynchronous messaging. DLR callback URLs are required in order to recieve error codes.

HTTPS use is mandatory; all attempts to use plain-text HTTP will be redirected to HTTPS. Request and response data requires JSON encoding. Only HTTP GET and POST methods are required.

Authentication

HTTP Basic Authentication is used for all requests. If you access the API without having the correct credentials OR permission to access the API, you will get a HTTP 401 response.

Your gateway application credentials (‘application name’ and password) are available on the platform: https://sms.optus.com.au/gateway/api_config/restv2

You will need a login and password to retrieve these.

If you don’t already have these details, 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 over HTTPS, and accessed from:

https://api.sms.optus.com.au/rest/sms/v2

Versions

The REST API version is currently v1. A custom media type is used to let consumers choose the data format they wish to receive:

Accept: application/vnd.modica.gateway.v1+json

OpenAPI Specification

The OpenAPI (Swagger) specification can be found at here.

You can see code samples and a breakdown of the specification here.

Error Codes

The following errors can occur:

Date Strings

Complete date plus hours, minutes, seconds & timezone.

YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)

     YYYY = four-digit year
     MM   = two-digit month (01=January, etc.)
     DD   = two-digit day of month (01 through 31)
     hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
     mm   = two digits of minute (00 through 59)
     ss   = two digits of second (00 through 59)
     s    = one or more digits representing a decimal fraction of a second
     TZD  = time zone designator (Z or +hh:mm or -hh:mm)

Sending messages

It is possible to send to either a single destination, or to broadcast one set of content to multiple destinations:

Sending to a single destination

To send an MT message to a single mobile handset, submit a POST request:

POST /messages
 
{
  "destination": "+6412345678",
  "content": "Your SMS message content with a very long https://a.urltoshorten.com/thatislongerthanthemaximummessagelength?withparameters=likethisone embedded in the text"
}

Optional attributes:

{
  "scheduled": str: 2017-05-05T10:00:00+12:00,  
  "source": str:short-code,
  "reference": str:alt-reference,
  "class": str:application-class,
  "mask": str:source-mask,
  "sms_class": int:0-3,
  "expires": str: 2017-05-05T10:00:00+12:00
}

On success:

HTTP/1.1 202 Accepted
Content-Type: application/json

{"id":"1e41f423-24cf-4fa2-9a8a-888c30653305","status":"accepted","detail":"+6412345678"}

On validation error:

HTTP/1.1 400 Bad Request
 
{
  "error": str:error-code
  "error-desc": [str:error-desc]
}

{
  "error-desc": "Invalid scheduled timestamp (must be less than 60 days)",
  "error": "invalid_attrib"
}

MO Callback

You will only receive MO messages if you have configured an MO callback URL within your API Configuration.

We recommend using https:// for your callback URLs.

When a MO message is received for you a POST request is made to the MO callback URL, this callback will include the MO message detail as a JSON object in the body of the POST request.

POST callback-url

{
  "id": str($uuid):message-id,
  "source": str:mobile-number,
  "destination": str:short-code,
  "content": str:text-message,
  "operator": str:operator-name
}

In the case that the message is a reply to an MT message an additional “reply_to” attribute is added (only when a number sequence is used, and the MO is in reply to an MT message):

{
  "reply_to": str:message-id
}

If the message contains a reply_to and the MT message had a reference provided, then an additional parameter will be added:

{
  "reference": str:reference
}

If the message from the handset contains binary content, one additional attribute will be supplied:

{
  "encoding": str:encoding-type
}

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.

DLR Callback

You will only receive DLR Status messages if you have configured a DLR callback URL within your API Configuration.

We recommend using https:// for your callback URLs.

When a DLR message is received for you a POST request is made to the DLR callback URL, this callback will include the DLR Status detail as a JSON object in the body of the POST request.

POST callback-url

{
  "message_id": str($uuid):message-id,
  "status": str:dlr-status
  "detail": str:detail
}

In the case that the MT message contained a reference, an additional “reference” attribute is added:

{
  "reference": str:alt-reference
}

DLR Message Status

The following are the status codes returned in DLRs that our message gateway supports.

Omni Message Status

The following are the status codes viewable within Omni reports that our message gateway supports, not all carriers will support all of them.