REST v1

Overview

Modica’s Mobile Gateway REST API allows you to schedule and/ or immediately send messages to a single handset, or broadcast to multiple handsets.

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 REST API configuration page in The Optus SMS Suite.

You will need a user account and password to retrieve these.

If you don’t 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/gateway

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 here: here.

You can see code examples and further information 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 (outbound) MT message to a single destination, submit a POST request:

POST /messages

{
  "destination": str:mobile-number,
  "content": str:text-message
}

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 201 Created
Location: https://api.sms.optus.com.au/rest/gateway/messages/int:message-id

[integer($int64):message-id]

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

Broadcasting to multiple destinations

To broadcast a common message to a multiple devices, submit the following POST request:

POST /messages/broadcast

{
  "destination": [str:mobile-number-1, str:mobile-number-2],
  "content": str:text-message
}

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 201 Created
Content-Type: application/json

[
  {
    "status": "success",
    "message": null,
    "destination": str:mobile-number,
    "id": integer($int64):message-id
  }
]

On validation error:

HTTP/1.1 400 Bad Request

{
  "error": str:error-code
  "error-desc": [str:error-desc]
}

Example showing a mixed response of successful and failed destinations:

HTTP/1.1 201 Created
Content-Type: application/json

[
  {
    "status": "success",
    "message": null,
    "destination": str:mobile-number,
    "id": integer($int64):message-id
  },
  {
    "status": "failure",
    "message": "Invalid destination (X)",
    "destination": "X",
    "id": null
  },
  {
    "status": "failure",
    "message": str:failure-reason,
    "destination": str:mobile-number,
    "id": null
  }
]

Retrieving an SMS Message

To retrieve a message submit a GET request:

GET /messages/id

If a match is found:

HTTP/1.1 200 OK
Location: https://api.sms.optus.com.au/rest/gateway/messages/int:message-id

{
  "id": str:message-id,
  "source": str:mobile-number|short-code,
  "destination": str:mobile-number|short-code,
  "content": str:text-message
}

Additional attributes are added if available:

{
  "reference": str:alt-reference,
  "reply_to": str:message-id,
  "operator": str:operator-name
}

If not found:

HTTP/1.1 404 Not Found

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
Location: https://api.sms.optus.com.au/rest/gateway/messages/int:message-id

{
  "id": int: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 Statuses 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:message-id,
  "status": str:dlr-status
}

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.

Help

Having trouble integrating with any of our services? Contact optussd@modicagroup.com and we’ll help you sort it out.