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 | To request a deliverey report, you need to set the value to "1". Also, DLR Callback URL should be configured under your Profile setting. | 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 |
| priority | To send high speed SMS (such as OTP SMS), you need to add this parameter (priority=high), or else operator will delayed your SMS request. Each operator have their own policy about this. | high |
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 Request Response
A standard successful SMS Request 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 | { |
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 |
| 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 |
| ERR014 | unknown destination number |
| 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 |
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.144.20.66
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.144.20.66
