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 | { |
Error Response: Insufficient balance
| HTTP Header | 200 OK |
| Content | { |
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: {
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 |
PT. Ayomobile Media International
Gedung Graha Kencana, Lt.10/G,
Jl. Raya Pejuangan No. 88
Jakarta, 11530
Indonesia
+62.21.53668160
info@ayosms.com
Copyright © 2003-2024
Made in Jakarta, Indonesia
Ohio, US - ENG/ID | 3.145.76.196
Gedung Graha Kencana, Lt.10/G,
Jl. Raya Pejuangan No. 88
Jakarta, 11530
Indonesia
+62.21.53668160
info@ayosms.com
Copyright © 2003-2024
Made in Jakarta, Indonesia
Ohio, US - ENG/ID | 3.145.76.196
