Send MT-SMS

All MT-SMS requests must be submitted to moceansms API Server at Base URL.

A response that indicate the success or failure of your request to moceansms API Server will be given for every request in XML format by default. In fact, you get to choose between XML or JSON format by setting value for optional parameter "mocean-resp-format" and submit along your MT-SMS request.

MT-SMS's actual delivery status is only confirm by referring to delivery report.

HTTP Method Supported

POST, GET - moceansms API Server can reads data either from HTTP Message Body or URL

Base URL

https://rest-api.moceansms.com/rest/1/sms

Parameters

Parameter Name

Data Format

Descriptions

mocean-api-key

* Required

string

Your account API key.

mocean-api-secret

* Required

string

Your account API secret.

mocean-from

* Required

string

SMS Sender ID (also referred as to SMS Sender Name) is the information that is displayed to the recipient as the sender of the SMS when a message is received at a mobile device.

mocean-to

* Required

phone number list

Phone number of the receiver. To send to multiple receivers, separate each entry with white space (‘ ’) or comma (,).

Phone number must include country code, for example, a Malaysian phone number will be like 60123456789.


NOTE: For the ease of error handling, we recommend putting only ONE receiver in one transaction.

mocean-text

* Required

string

Contents of the message, URL encoded as necessary (e.g. Text+message+test%21). If you are sending binary content, this will be a hex string. For example, 030616AE966C6F...

mocean-udh

* Optional

string

User Data Header (UDH) part of the message. For example, 0605040B8423F0.

mocean-coding

* Optional

number

Sets the coding scheme bits in DCS field. Accepts values 1 to 3, for 7-bit, 8-bit and UCS2 respectively. If unset, defaults to 7 bits unless a mocean-udh is defined, which sets coding to 8-bit. If charset is not set or set to UTF-8, when non-GSM character is detected, coding will set to UCS2.

mocean-dlr-mask

* Optional

number

Request for delivery reports with the state of the sent message. To enable delivery reports, set this value to ‘1’. If this field is not specified, the default value will be ‘0’ and no DLR will be returned.

mocean-dlr-url

* Optional

URL

URL to receive delivery reports. This is required if DLR is requested.

mocean-schedule

* Optional

datetime

When this field is used, the message will be sent out on the specified date time (on best effort basis due to large number of SMS is queued for scheduling).


The format of the date time is YYYY-MM-DD hh:mm:ss (in 24-hours format, e.g. 2007-02-11 23:30:00). The wrong date format will cause the gateway to reject the request.


NOTE: Please use Malaysia time (or GMT +8:00) while making scheduled SMS request.

mocean-mclass1

* Optional

number

To send Flash SMS, set mocean-mclass and mocean-alt-dcs value to '1'.

mocean-alt-dcs1

* Optional

number

To send Flash SMS, set mocean-mclass and mocean-alt-dcs value to '1'.

mocean-charset2

* Optional

string

Indicates the character set used in the mocean-text parameter. Supported character sets are:

1. ISO-8859-1

2. ISO-8859-7

3. UTF-8

4. Windows-1252

mocean-validity

* Optional

number

To define the validity period of message. User has to input validity in terms of SECONDS. For example, if user wants message to expire after 5 minutes upon submission, user has to configure mocean-validity as 300.

mocean-resp-format

* Optional

string

Response format. By default, response format will be returned in XML. Supported formats are:

1. XML

2. JSON

Note1: Not every carrier/route support Flash SMS and the ability to receive/display Flash SMS is handset dependent.

Note2: Please use EXACT wording as indicated in the table above.

Example Request

curl -X POST "https://rest-api.moceansms.com/rest/1/sms" -d "mocean-api-key={api_key}&mocean-api-secret={api_secret}&mocean-from=YourCompany&mocean-to=60123456789&mocean-text=Hello"
$url = 'https://rest-api.moceansms.com/rest/1/sms';

$params = array(
'mocean-api-key' => 'API_KEY',
'mocean-api-secret' => 'API-SECRET',
'mocean-to' => '60123456789',
'mocean-from' => 'YourCompany',
'mocean-text' => 'Hello',
'mocean-resp-format' => 'json',
'mocean-charset' => 'UTF-8',
'mocean-dlr-mask' => 1
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$response = curl_exec($ch);
curl_close ($ch);
echo $response;
<html>
<head>

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body>

<form name="form1" action="https://rest-api.moceansms.com/rest/1/sms" method="post">
<table>

<tr><td>Username:</td>
<td><input type="text" name="mocean-api-key" value="" placeholder="api-key"></td>
</tr>

<tr><td>Password:</td>
<td><input type="text" name="mocean-api-secret" value="" placeholder="api-secret"></td>
</tr>

<tr><td>From:</td>
<td><input type="text" name="mocean-from" value="" placeholder="your company"></td>
</tr>

<tr><td>To:</td>
<td><input type="text" name="mocean-to" value="" placeholder="60123456789"></td>
</tr>

<tr><td>Message:</td>
<td><input type="text" name="mocean-text" value="" placeholder="your text"> </td>
</tr>

<tr><td>Coding:</td>
<td><input type="text" name="mocean-coding" value="" placeholder="coding"></td>
</tr>

<tr><td colspan=2><input type="Submit"></tr>

</table>
</form>

</body>
</html>

Example Response

A successful response for MT-SMS will be as follows:

<result>
<message>
    <status>0</status>
    <receiver>60173788399</receiver>
    <msgid>cust20013050311050614001</msgid>
</message>
</result>                
                    
{
"messages":[
{
  "status":0,
  "receiver":"60173788399",
  "msgid":"cust20013050311050614001"
}
]
}    
        

While unsuccessful response will be as follows:

<result>
    <message>
        <status>1</status>
        <err_msg>Authorization failed</err_msg>
    </message>
</result> 
<result>
    <message>
        <status>2</status>
        <receiver>60123456789</receiver>
        <err_msg>Insufficient credits to send sms</err_msg>
    </message>
</result> 
<result>
    <message>
        <status>3</status>
        <receiver>60123456789</receiver>
        <err_msg>No rate found</err_msg>
    </message>
</result> 
{
"messages":[
{
  "status":1,
  "err_msg":"Authorization failed"
}
]
}    
{
"messages":[
{
  "status":2,
  "receiver": "60123456789",
  "err_msg":"Insufficient credits to send sms"
}
]
}    
{
"messages":[
{
  "status":3,
  "receiver": "60123456789",
  "err_msg":"No rate found"
}
]
}    

MT-SMS Response Variables

Parameter Name

Data Format

Descriptions

status

number

Status of the submission, refer to MT-SMS Response Status Codes below for complete list of status

receiver

string

mocean-topassed in during submission.

msgid

string

Message ID assigned to the message, this will be used as a reference when the delivery report is sent back to indicate message delivery status.


If the message is sent to multiple destination numbers, for example, if mocean-to was set to “60123456789 60198765432”, response format will be as follows:


<message>

<status>0</status>

<receiver>60123456789</receiver>

<msgid>cust20013050311055243001</msgid>

</message>


<message>

<status>0</status>

<receiver>60198765432</receiver>

<msgid>cust20013050311055243002</msgid>

</message>


err_msg

string

Error message.

MT-SMS Response Status Codes

Status Code

Descriptions

0

OK. No error encountered.

1

Authorization failed. Invalid mocean-api-key or mocean-api-secret.

NOTE: When this error is encountered, NO SMS is sent to any of the receivers.

2

Insufficient balance. Not enough credit in the account to send to at least one of the receivers.

4

At least one of the destination numbers is not white listed.

5

At least one of the destination numbers is black listed.

6

No destination number specified.

8

Sender ID not found.

9

Invalid UDH field.

10

Invalid mclass field.

17

Invalid validity field.

19

Invalid character set or message body.

20

Insufficient headers for sending SMS.

23

Empty mocean-text.

24

Unknown error.

26

Invalid schedule format. (Hint: must have leading zero for time.)

2007-03-02 08:55:00 is correct.

2007-03-02 8:55:00 is not correct.

27

Max number of receivers in a single request reached. Too many receivers in mocean-to field.

28

Invalid destination number. Receiver is invalid after stripping all non-numerics.

29

Message body is too long.

32

Message throttled.

34

Unknown request.

37

Invalid sender length.

40

System down for maintenance.

43

SMS flooding detected.

44

Invalid Sender ID.

45

System error, please retry later.

48

At least one of the senders is black listed.

49

At least one of the senders is not white listed.

50

Inappropriate content detected.