AYOSMS! - Send HLR API

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

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.131.13.194

FAQ
Register
Payment

Reseller Program
API

Contact
Company Info