Send SMS API

The following sections describe the request URL to send SMS from AYOSMS! SMS API and all of its associated input parameters and their corresponding values.

Endpoint URL

All the requests to AYOSMS! must be submitted to following Endpoint URL:

https://api.ayosms.com/mconnect/gw/sendsms.php

Input Parameters

The following table lists each parameter that can be submitted together with the Endpoint URL given above. Note that the first 4 parameters are mandatory while remaining is optional. All parameters are case sensitive.


Parameter Description Example Values
api_key Mandatory AYOSMS! account API Key. 11877c8e0ac231ca93ec2cfcbe1820eb
from Mandatory Sender ID of the message. Up to 11 alphanumeric characters. 7-bit karakter. AYOSMS%21
to Mandatory Destination mobile number in international format (prefixed with country code but without the '+' sign). Accept multi destinations using comma ',' separated value. 62811990000,628999900000
msg Mandatory The SMS text to send URL encoded in Unicode UTF-8. Limited to 400 characters. Accept only 7-bit characters. Hello+World%21
trx_id Unique internal transaction reference supplied by user to aid with matching delivery receipts. Accept only 7-bit characters. Limited to 36 characters. ae75fa6b-aa5d-4ea9-9ce7-d7db9da760af
dlr By default, delivery receipt (DLR) is returned for all messages. There is no need to configure this parameter on API level. However, DLR Callback URL should be configured under your Profile setting to set delivery receipt callback URL. 1
delivery_time Scheduled message for future delivery. Format for setting datetime: yyyymmddMMii (yyyy=year, mm=month, dd=date, MM=hour, ii=minutes). Date time is in GMT+7. Defaults to Immediate delivery. 201704070815

Send Respond

AYOSMS! SMS API returns a response in 2 parts:
  • HTTP Header Status (typically with a HTTP status code 200 OK to indicate successful API call)
  • HTTP Content (In JSON format)

Successful SMS Send Response

A standard successful SMS Send Response shall return status code as '1' and a unique msg_id to identify each SMS send request (and optionaly a trx_id value if you fill it when you make a request to Send API):
HTTP Header 200 OK
Content
{
msg_id : "0ca9265c543baf107d3d1feda03aa4d5-1",
trx_id : "123456",
status : 1,
segment : 1
}

Error Response: Insufficient balance

HTTP Header 200 OK
Content
{
msg_id : "0ca9265c543baf107d3d1feda03aa4d5-1",
trx_id : "123456",
status : 0,
error-text : "ERR002:insufficient balance"
}

Response Attributes

Parameter Description
status Status code. '1' indicates Successful Request, while '0' for Unsuccessful Request (For Error codes, please refer to Error Response Code section below)
msg_id Unique ID to identify a successful SMS send request. Used to trace and match against the ID returned in Delivery Receipt.
trx_id Unique internal transaction reference supplied by user in the API request
segment How many SMS segment. AYOSMS! only support GSM 7bit characters. 1-160 characters are counted as 1 SMS segment. More than 160 characters, SMS will be splited into 153 characters per segment. 1 SMS segment cost is equal to 1 SMS request.
error-text Error codes followed by error explanation

Error Response Code

Response Code Description
ERR001 account suspended
ERR002 insufficient balance
ERR005 "from" parameter error or empty
ERR006 "to" parameter error or empty
ERR007 "msg" parameter error or empty
ERR008 api_key not found or sender is disabled
ERR009 sender not registered
ERR010 delivery time happened in the past
ERR012 non GSM 7bit character found
ERR013 more than 400 characters SMS
ERR999 api_key is empty

Example

To send a plain SMS, Hello world! to 62811000000 with sender id as "AYOSMS!"

https://api.ayosms.com/mconnect/gw/sendsms.php?api_key=your_unique_api_key&from=AYOSMS%21&to=62811000000&msg=Hello+world%21&trx_id=mytrxid12345
Parameter Value in Request Description
api_key your_unique_api_key Your AYOSMS! Account API Key
from AYOSMS%21 (URL encoded for "AYOSMS!") The sender ID (URL encoded)
to 62811000000 The destination mobile number in international format (prefixed with country code but without the '+' sign)
msg Hello+world%21 (URL encoded for "Hello world!") The message content (URL encoded)
trx_id mytrxid12345 Your Transaction ID reference

Delivery Report

A Delivery Receipt (DLR), also known as Delivery Report, is a special type of message which indicates the final state of a SMS.

Requesting A Delivery Report

A Delivery Receipt is not requested by default for every SMS submission. The DLR parameter must set to "1" (dlr=1) in your AYOSMS! SMS API request/

DLR Callback Request

<Your_DLR_Callback_URL>?msg_id=0ca9265c543baf107d3d1feda03aa4d5-1&trx_id=mytrxid12345&from=AYOSMS%21&to=62811000000&delivered=1460019615&status=1&error-text=DELIVERED

Once AYOSMS! receives a delivery receipt, a HTTP DLR callback request will be made to your DLR Callback URL with following parameters described below:

Parameter Description
msg_id Unique ID to match against the ID returned in the SMS API response.
trx_id Unique internal transaction reference supplied by user in the API request.
from Sender ID of the message.
to Destination mobile number in international format (prefixed with country code but without the '+' sign).
delivered Time when AYOSMS! received a Delivery Report from operator (in UNIX Timestamp format, GMT+7).
status Always return '1' for delivered to destination number, and '0' for others (such as permanent failed/pending/buffering etc)
error-text Delivery Receipt error code. (For other DLR error codes, please refer to DLR Error Code section below)
Error-text:
DELIVERED
PENDING
FAILED
EXPIRED
GENERATING MPOSTER URL
NO ROUTE TO DESTINATION NUMBER
SENT NOT DELIVERED

Successful DR Receive Response

Your system HAVE TO respond with plain text "OK". AYOSMS! system will try up to 10 times until we receive an "OK" text from your system.
HTTP Header 200 OK
Content
OK
SMSMOO
AYOMOBILE!