Video Guide
Last Update: 21st Apr 2021
Developer Guide
Introduction
We can't wait to launch every new release and new features everytime after it pass thru Acceptance Test. Continue from all API features in previous version, this time we have implemented OAuth2.0 Client Credentials in the API request.
In Bulk360 SMS API V1.x, Access Credentials are shared across our Web Portal and API; in other word, when You change your account password, Your API fails to work immediately due to outdate password in your existing Application. We have solve it by implementing OAuth2.0 Client Credentials Authentication.
With Bulk360 SMS APIs, an enterprise level SMS Gateway allowing you to send both SMS and WhatsApp message at a single request. Start creating your amazing application and leverage on our Digital Marketing Tools!
This document will cover the following areas of connectivity:Summary Changes
This release aims to implement more features based on our customers' feedback and features requested
New features in V2.0:- OAuth2.0
- Your Account Credentials would not be exposed in URL query string anymore
- Separate Credentials
- Access Credentials can be change anytime without any API down time
- Increase Security
- The new release API accepts only POST Request
Overview of Bulk360 API V2.0 Flow
Below figure shows One Way SMS call flow
- Client request access token by given connection credentials
- Bulk360 return granted access token
- Client request send SMS using the granted access token
-
Bulk360 acknowledge upon MT received, and return a Unique Reference ID. The returning values as specified in HTTP Response
Noted that the MT Status here is not final - Bulk360 transmit the MT to the recipient's Telco, Acknowledgement and Reference ID return from Telco
- Delivery Notification [DN] return from Telco
- Bulk360 return DN with Final Status of the MT Sent, refers to Delivery Notification for returned values
Request Access Token
You need to provide Access Token in order to send SMS using API V2.0. To request the Access Token, send a POST request to following URL together with your APP_KEY and APP_SECRET:Your APP_KEY and APP_SECRET is located at Configurations > APIs > Create Connection.
Your example of PHP code might look like this:$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sms.360.my/oauth/token",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "grant_type=client_credentials&client_id=YOUR_APP_KEY&client_secret=YOUR_APP_SECRET",
CURLOPT_HTTPHEADER => [
"Accept: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
{
"token_type" : "Bearer",
"expires_in" : 3600,
"access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxOCIsImp0aSI6IjRmOGZkOWFjNGE2NjJiMzc3NTYzYjYxZGViOGQ1N2E0YjhjMjZmOTE3NmNkOTJkMWNkMjdiMzUzNGU3NmFjMDg4YjA1ODYxZTcwMTZjYTg0IiwiaWF0IjoxNjE4MDc4NDg0Ljk5MjcwMywibmJmIjoxNjE4MDc4NDg0Ljk5MjcxMiwiZXhwIjoxNjE4MDgyMDg0Ljg5NjE1LCJzdWIiOiIiLCJzY29wZXMiOlsiKiJdfQ.oK4QdL4TZDWmN9vOHcUozzFhphABdTtPJFo-AU4daIEW_x-yWVDTQVS-o2O7v7clEHARSehA08pjwP3uaaVMPvZq0NFYH1R5Nvfw9d0fdPbuDr8nczkvuJlCTGvOkw2mHzwhjAmkXsMERYDL3OfJ7h86ILqv6C56fe5kidsa6JyMF0A1Jv_u0E8N1GpxkSM5_8YcCghTnAVGLsg3e-zrkOb_4Umg_LIogFFvyx1PlvOX51Vlx2PEkyoQhInXGd7VwBSFvWeKrI-3nlUxMwuW1D0Gr1bFh5aHURaFQ84FulDzl3ND7P8Oj2nAe7g85iArRNKdZe9Xem8MaRxn3VT1DumHRHdAtbk-_vyw0G1VW2zyx58IWSsYcAqNZW4s97oC-HAvX18t1JyvUHpynKi1MKgdCGirhvIYsyWkz_Tmw2M_eGMgEzr9GfvGUGgu3cKtzd39eAQMMfvH-Z1_89uep9XapbazKXxb_G-d-4GIk411OBCzIWLfs8KcpjYWRVnwfj91mmC8qIQ_3CriettrLUs3rWYQ4ax7PrW9XiZsEScyEn0g7OyO5OnK57qhnGRuCc8gJUmo9DfkDeYYeRhCbmz1JKRUYN9t-qf4QfxFVgLPe7h4QqMiUy2K_mPoGHfkIFSSsZ2dYc7DKp_dKLOmDTXPG9Q_ajtvbq18Fjq43yE"
}
{
"error" : "invalid_client",
"error_description" : "Client authentication failed",
"message" : "Client authentication failed"
}
Refer to above expires_in: 3600, the granted Access Token is valid for 3600 seconds (1 hour), you shall request new token only when it's expired to increase your sending speed.
Sending Normal Text Messages
Mobile Terminated (MT) Message refers to a message being sent out from SMS Gateway to the mobile handset. Our HTTP API is designed for developers with instructions to integrate Bulk360 SMS services into various solutions.
To send SMS, only POST request shall be submitted to following URL:
Below table explanation for all required Parameters:
| # | Parameter | Description | Mandatory | Example |
|---|---|---|---|---|
| 1 | to | Maximum 150 characters Recipient's mobile number in international format (without the "+" sign) To send multiple recipeints in a single request, separate each recipient entry with comma (,) eg. 60123240066,60102200533,60166600267 To send WhatsApp message, just add 'whatsapp:' as prefix of the mobile entry eg. 60123240066,60102200533,whatsapp:60166600267 |
Yes | 60123240066 |
| 2 | from | The source name of the SMS, it accepts Maximum of 11 alphanumeric characters. [Not applicable in Malaysia] | No | AEONSales |
| 3 | text | The SMS content. When sending MT to Malaysia prefix (60) is concerned, the system will auto append “RM0 ” at the beginning of the SMS content. This will consume 4 characters from the total characters count of the message & credits will be deducted accordingly | Yes | Message from Bulk360 Gateway |
| 4 | detail |
To show additional info of: - Account Balance The balance returned is the balance before you trigger send the transaction - Charge for each MSISDN - Currency for each charge |
No | 1 |
$sms_data = [
'from' => '68068',
'to' => '60123240066',
'text' => 'Hi from Bulk360 SMS API V2.0',
'detail' => 1
];
$query_string = http_build_query($sms_data);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sms.360.my/api/bulk360/v2.0",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $query_string,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . YOUR_ACCESS_TOKEN,
"Accept: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
If detail=1 is provided, the API will return 4 values as specified in HTTP Response
If detail=1 is not provided, the API will only return 3 values without Currency and Account Balance
{
"code" : 200,
"desc" : "OK",
"to" : "60123240066",
"ref" : "E210446dBNyMYd7",
"currency" : "MYR",
"balance" : "187.9236"
}
{
"messages": [
{
"code": 200,
"desc": "OK",
"to": "60123240066",
"ref": "E2104yMYer2weOB-X46dBlYa79",
"currency": "MYR",
"rate": 0.11
},
{
"code": 200,
"desc": "OK",
"to": "60126660125",
"ref": "E2104gl9avQVeG1-oBDbDpKbl2",
"currency": "MYR",
"rate": "0.2500"
}
],
"currency": "MYR",
"balance": "4229.8700"
}
{
"code": 400,
"desc": "Missing parameters or invalid field type"
}
Sending UNICODE (UCS2) messages (Multi lingual)
To send language such as Chinese, Hindi or Thai, simply assign your non-latin script into a variable and you are good to send.
Your example of PHP code might look like this:$sms_data = [
'from' => '68068',
'to' => '60123240066',
'text' => '您好, 这是发自 Bulk360 SMS Client API V2.0的短信',
'detail' => 1
];
$query_string = http_build_query($sms_data);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sms.360.my/api/bulk360/v2.0",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $query_string,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . YOUR_ACCESS_TOKEN,
"Accept: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
HTTP Response
Upon the Bulk360 SMS API is called, the API will return 4 values:- code - The real-time delivery status, refer to following table Response Code
- desc - Description of the code
- to - Recipient mobile number
- ref - Reference ID returned by 360
- optional - [with parameter 'detail=1']
- Currency
- Account Balance
| Response Code | Description |
|---|---|
| 200 | OK |
| 400 | Missing parameters or invalid field type |
| 401 | Invalid Username or password |
| 402 | Insufficient Account credit |
| 403 | Email or Mobile Number not verify, message API not enabled, requested IP not whitelisted or not enabled |
| 405 | Invalid Message Type |
| 406 | Message content is not approved If you sending Whatsapp Message, please submit your WhatsApp message content for approval |
| 407 | Banned Content detected. Your account is suspended |
| 412 | Account suspended / Terminated / Not activated |
| 413 | Account under observation mode, limited features enabled |
| 500 | Internal server error |
| DELIVERED | Message successfully delivered to the mobile handset |
| UNDELIVERED | Message failed to be delivered to the mobile handset |
{
"code" : 200,
"desc" : "OK",
"to" : "60123240066",
"ref" : "E210446dBNyMYd7"
}
{
"code" : 200,
"desc" : "OK",
"to" : "60123240066",
"ref" : "E210446dBNyMYd7",
"currency" : "MYR",
"balance" : "187.9236"
}
{
"messages": [
{
"code": 200,
"desc": "OK",
"to": "60123240066",
"ref": "E2104yMYer2weOB-X46dBlYa79",
},
{
"code": 200,
"desc": "OK",
"to": "60126660125",
"ref": "E2104gl9avQVeG1-oBDbDpKbl2",
}
]
}
{
"messages": [
{
"code": 200,
"desc": "OK",
"to": "60123240066",
"ref": "E2104yMYer2weOB-X46dBlYa79",
"currency": "MYR",
"rate": 0.11
},
{
"code": 200,
"desc": "OK",
"to": "60126660125",
"ref": "E2104gl9avQVeG1-oBDbDpKbl2",
"currency": "MYR",
"rate": "0.2500"
}
],
"currency": "MYR",
"balance": "4229.8700"
}
Delivery Notification (DN)
Delivery Notification is the final status of your Message sent. Note that not all Telco would return DN, or certain telco might return SMSC receipt rather than handset receipt
If Delivery Notification is required, please fill in the Delivery Notification Hook located at My Configurations > APIs tab. DNs will then be forwarded to your DN URL in real time in following format:
Four parameters return as below:| # | Parameter | Description | Example |
|---|---|---|---|
| 1 | status | Real-time DN Status | DELIVERED or UNDELIVERED |
| 2 | error-code | Error Details. Optional, we wouldn't return this parameter if non has return from Telco | 000 or 50 |
| 3 | msisdn | MT recipient mobile number | 60123240066 |
| 4 | msgid | The Reference ID enables client to tie the DN with the MT sent | 5515023 |
Note:
- The total number of DNs returned will be based on the number of Message broadcasted. E.g.: if a Group of broadcast consists of 10 MSISDNs, there will be 10 DNs returned. If there were more than 1 DN returned for the same Message, always consider the last DN received as the final DN.
- Depending on Telcos' configuration, MT retries attempt might be prolonged for 36 to 48 hours if cell phone is unreachable.
| Error Code | Description |
|---|---|
| 000 | No Error |
| 50 | Unknown Error / Not specify |
| 501 | Absent Subscriber |
| 502 | Handset memory capacity exceeded. Handset has run out of free memory to store new message |
| 503 | Equipment protocol error |
| 504 | Equipment not equipped with short-message capability |
| 505 | Unknown subscriber. The IMSI is unknown in the HLR |
| 506 | Illegal subscriber. The mobile station failed authentication |
| 507 | Teleservice not provisioned. Mobile subscription identified by the mobile number does include the short message service |
| 508 | Illegal equipment. IMEI check failed, i.e. the IMEI is either black listed or not white listed |
| 509 | Call barred. Operator barred the mobile number |
| 510 | Facility not supported. VLR in the PLMN does not support MT short message service |
| 511 | Subscriber busy for MT short message |
| 512 | System failure. Task cannot be completed because of a problem in another entity |
| 513 | Data missing. Necessary parameter is not present in the primitive |
| 514 | Unexpected data value. Necessary data is badly formatted in the primitive |
| 515 | Unidentified subscriber |
| 516 | Absent subscriber. No paging response |
| 517 | Absent subscriber. IMSI detached |
| 518 | Absent subscriber. Roaming restriction |
| 547 | Application context not supported |
| 550 | Temporary error received from peer SMSC |
| 551 | SMS malformed. SMS is not formed correctly. This error is specific to IP-based protocols like SMPP |
| 552 | SMS expired |
| 553 | Insufficient credit. The user has insufficient credit/not allowed to send to that destination |
| 554 | Invalid destination. Receiver is not a valid number |
| 555 | Unable to find outbound route for this SMS |
| 556 | SMS buffered |
| 557 | Timeout waiting for response from peer |
| 558 | Throttling error. The user has exceeded allowed message limit |
| 561 | Subscriber blacklisted |
| 562 | Subscriber not white listed |
| 569 | Invalid sender ID |
| 571 | Subscriber opted out from receiving SMS |
| 574 | SMS rejected. Error received from peer SMSC |
| 575 | SMS rejected. Inappropriate SMS content |
| 576 | Sender ID blacklisted |
| 577 | Sender ID not while listed |