SOAP API

Overview

Our SOAP gateway Web Service Definition Language (WSDL) is located here: https://api.sms.optus.com.au/ModicaSoap.wsdl

To send an SMS via SOAP, use the sendMessage operation.

You must access the Web Service via https, attempts to use http will be redirected to their equivalent http URL.

Parameters

The SOAP method to use for delivering an SMS to a mobile phone is named ‘sendMessage’ in the WSDL.

The parameters of this method are:

For more information on SMS character sets and SMS concatenation please visit:

• https://en.wikipedia.org/wiki/Concatenated_SMS

• Modica can deliver full GSM 0.038 Extended character set, excluding the following characters: ¤ ¡ § |

• https://en.wikipedia.org/wiki/GSM_03.38

Sending SMS (SOAP)

To send your SMS application via SOAP, use the  sendMessage  method as defined in the  WSDL .

MO Callback

If you have supplied an MO callback URL within your API configuration.

When an MO message is received and routed to your application, a GET request is made to your MO callback URL. When you set the MO callback URL your URL should not contain a query string as that is automatically appended.

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

Your server will then receive a GET request like this:

GET https://yourserver.example.com/receiveMessage?id=12345&source=%2B642741234567&destination=4433&content=SMS+message+content+here&operator=Telecom_NZ

The will contain the following GET parameters:

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

DLR Callback

If you have supplied an DLR callback URL within your API configuration.

When an DLR message is received for an MT message sent by your application, a GET request is made to the DLR callback URL. When you set the DLR callback URL your URL should not contain a query string as that is automatically appended.

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

Your server will then receive a GET request like this:

GET https://yourserver.com/receiveStatus?id=54321&status=received

The will contain the following GET parameters:

When an SMS MT message is successfully submitted via SOAP the gateway message ID is returned.

In order to track the status of a message you will need to store that ID, as status callback will use the ID to reference the message.

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:

Example

https://yourserver.com/receiveStatus?id=54321&status=received

When an SMS MT message is successfully submitted via SOAP the gateway message ID is returned.

In order to track the status of a message you will need to store that ID, as status callback will use the ID to reference the message.

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.

<?php
define('WSDL_URL','https://api.sms.optus.com.au/ModicaSoap.wsdl');
define('APPLICATION', 'your_application_name');
define('PASSWORD', 'password');
define('SEND_TO_MOBILE','+6421xxxxxxx'); // Mobile # Intl Format
define('MESSAGE_CLASS','mt_message');
define('MESSAGE_REFERENCE','');

try {
    $client = new SoapClient(
        WSDL_URL,
        array(
            'trace' => true,
            'exceptions' => true
        )
    );
    $return = $client->sendMessage(
        array('application' => APPLICATION,
              'password'    => PASSWORD,
              'destination' => SEND_TO_MOBILE,
              'content'     => 'This is a test message.',
              'reference'   => MESSAGE_REFERENCE,
              'class'       => MESSAGE_CLASS)
    );
} catch (SoapFault $fault) {
    // log error here
}
?>

Error Codes

The response that the gateway returns on errors will depend on the API version you request.   The following errors can occur:

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.