Send HLR API

The following sections describe the request URL to send HLR from AYOSMS! HLR 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/sendhlr.php

Input Parameters

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


Parameter Description Example Values
api_key Mandatory AYOSMS! account API Key. 11877c8e0ac231ca93ec2cfcbe1820eb
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
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
delivery_time Scheduled HLR for future execution. Format for setting datetime: yyyymmddMM (yyyy=year, mm=month, dd=date, MM=hour). Date time is in GMT+7. Defaults to Immediate delivery. 2015112515

Send Respond

AYOSMS! HLR 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 HLR Send Response

A standard successful HLR Send Response shall return status code as '1' and a unique msg_id to identify each HLR 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
}

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
error-text Error codes followed by error explanation

Error Response Code

Response Code Description
ERR001 account suspended
ERR002 insufficient balance
ERR006 "to" parameter error or empty
ERR008 api_key not found or sender is disabled
ERR009 sender not registered
ERR010 request execution happened in the past
ERR999 api_key is empty

Example

To request a HLR to 62811000000

https://api.ayosms.com/mconnect/gw/sendhlr.php?api_key=your_unique_api_key&to=62811000000&trx_id=mytrxid12345
Parameter Value in Request Description
api_key your_unique_api_key Your AYOSMS! Account API Key
to 62811000000 The destination mobile number in international format (prefixed with country code but without the '+' sign)
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 HLR.

Requesting A Delivery Report

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

DLR Callback Request

<Your_DLR_Callback_URL>?msg_id=0ca9265c543baf107d3d1feda03aa4d5-1&trx_id=mytrxid12345&to=62811000000&delivered=1460019615&status=1&error-text=DELIVERED&meta-data=%7B%22countrycode%22%3A%22id%22%2C%22country%22%3A%22Indonesia%22%2C%22networkcode%22%3A%2251010%22%2C%22operator%22%3A%22TELKOMSEL%22%7D

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.
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
REJECTED
NO ROUTE TO DESTINATION NUMBER
UNKNOWN SUBSCIBER (IMSI IS UNKNOWN IN THE HLR)
SENT NOT DELIVERED
meta-data Additional info for Country Code, Network Code and Operator Name. This additional info will be in JSON (url-encoded) format.
Example:
{
countrycode : "id",
country : "Indonesia",
networkcode : "51010",
operator : "TELKOMSEL"
}

Url-encoded:
%7B%22countrycode%22%3A%22id%22%2C%22country%22%3A%22Indonesia%22%2C%22networkcode%22%3A%2251010%22%2C%22operator%22%3A%22TELKOMSEL%22%7D

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!