Bulk360 SMS API V3.0

Video Guide

Last Update: 29th Sep 2021

Developer Guide

Introduction

We can't wait to launch every new release and new features everytime after it pass thru Acceptance Test. This time we have increased API processing speed by 13 times faster compare to previous version.

360 makes sending and receiving SMS easy. With Bulk360 SMS APIs, an enterprise level SMS Gateway capable to handle millions of transactions daily. 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 are launched based on our internal feedback and achievement to increase the capacity to handle more traffics. Upon your API request, we will accept the traffic as long as you have provided the correct credentials, IP whitelisted and enabled; we will return send status (such as Delivered, Failed, Insufficient balance, Account suspended) in Delivery Notification [DN].

New features in V3.0:
Separate Credentials
API Credentials can be change anytime without any impact or down time
Handling Speed
14 times faster compare to previous version
Obsolete OAuth2.0
OAuth2.0 is removed due to performance concern
For User in V1.4: Steps to migrate to V3.0:
  1. Change your API submission from:
    https://sms.360.my/gw/bulk360/v1.4
    change to:
    https://sms.360.my/gw/bulk360/v3_0/send.php
  2. Change API request by providing APP_KEY in user parameter and APP_SECRET in pass parameter
    Your APP_KEY and APP_SECRET is located at Configurations > APIs > Create Connection.
  3. Understand and update system based on json object return from our system

For User in V2.0: Steps to migrate to V3.0:
Change your API submission from:
https://sms.360.my/api/bulk360/v2.0
change to:
https://sms.360.my/gw/bulk360/v3_0/send.php

Overview of One Way SMS Flow

Below figure shows One Way SMS call flow
  1. Client request send SMS via Bulk360 SMS API [MT]
  2. 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
  3. Bulk360 transmit the MT to the recipient's Telco, Acknowledgement and Reference ID return from Telco
  4. Delivery Notification [DN] return from Telco
  5. Bulk360 return DN with Final Status of the MT Sent, refers to Delivery Notification for returned values

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. This guide will walk you through the process of sending messages by simply submitting your information either a POST or GET request to our API.

However, the POST method is recommended as opposed to the GET method due to the limitation of size and credentials are exposed in the URL.

To send SMS, all POST / GET request shall be submitted to following URL:
Actual working example with mandatory parameters:
Below table explanation for all Parameters:
# Parameter Description Mandatory Example
1 user APP_KEY capture from Configurations > APIs > Create Connection Yes 7LrdwRb1Ya
2 pass APP_SECRET capture from Configurations > APIs > Create Connection Yes aAjc9I7mW5eGzxwYs
3 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
4 from The source name of the SMS, it accepts Maximum of 11 alphanumeric characters. [Not applicable in Malaysia] No AEONSales
5 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
6 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
* All parameters must be encoded in URL format if API triggered via GET Request
Following sample source code in different languages:

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

Example of a wrong APP_KEY and APP_SECRET combination:
{
    "code"   : 401,
    "desc"   : "Invalid Username or password"
}
Example of a successful response for 1 recipient:
{
    "code"       : 200,
    "desc"       : "OK",
    "to"         : "60123240066",
    "ref"        : "78-1633193001.0602"
}
Example of a successful response for 1 recipient (with detail=1):
{
    "code"       : 200,
    "desc"       : "OK",
    "to"         : "60123240066",
    "ref"        : "78-1633193032.8416",
    "currency"   : "MYR",
    "balance"    : "187.9236"
}
Example of a missing any mandatory field(s):
{
    "code": 400,
    "desc": "Missing parameters or invalid field type"
}

Sending UNICODE (UCS2) messages (Multi lingual)

You are able to send Message in any language such as Chinese, Hindi or Thai with ease. Simply encode your Double Characters content into URL format.

Actual working example with mandatory parameters:

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

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

Note that due to MT are queued for process later, the return Balance is not included the charges incur by current request.

Response Code Description
200 OK
400 Missing parameters or invalid field type
401 Invalid Username or password
402 Insufficient Account credit
403 Message API not enabled, requested IP not whitelisted or not enabled
405 Invalid Message Type. Mobile numbers provided involved multiple services (SMS & WhatsApp), you can only trigger 1 service in 1 API request
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
Example of HTTP response returning:
{
    "code"       : 200,
    "desc"       : "OK",
    "to"         : "60123240066",
    "ref"        : "78-1633193001.0602"
}
Example of HTTP response returning with parameter 'detail=1':
{
    "code"       : 200,
    "desc"       : "OK",
    "to"         : "60123240066",
    "ref"        : "78-1633193001.0602",
    "currency"   : "MYR",
    "balance"    : "187.9236"
}
Example of HTTP response returning with multiple recipients:
{
    "code"       : 200,
    "desc"       : "OK",
    "to"         : "60123240066,60176655668,60102200533,60102410102,60143600661",
    "ref"        : "78-1633193001.0602",
    "currency"   : "MYR",
    "balance"    : "187.9236"
}

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 78-1633193001.0602

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 minimum of 10 DNs returned. If there were more than 1 DN returned for the same Message, always consider the last status of DN as the final DN. For example, if SENT status return after DELIVERED status, consider the message has been successfully delivered.
- 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
20 Message sent to carrier partner
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
Example of DNs for multiple numbers in single API Request:
# If you sent 3 numbers in 1 API request, eg:
https://sms.360.my/gw/bulk360/v3_0/send.php?user=7LrdwRb1Ya&pass=aAjc9I7mW5eGzxwYsdzGjKdkF3obLaOmrXUTZizH&to=60123240066,60102200533,60102410102&from=AEONSales&detail=1&text=Message+from+360+Gateway

# Respond from above:
{
    "code"       : 200,
    "desc"       : "OK",
    "to"         : "60123240066,60102200533,60102410102",
    "ref"        : "78-1633193001.0602",
    "currency"   : "MYR",
    "balance"    : "187.9236"
}


# You would receive minimum 3 DNs
# 1st DN:
{
    "status"       : SENT,
    "error-code"   : 20,
    "msisdn"       : 60123240066,
    "msgid"        : "78-1633193001.0602-0"     # 0 refers to DN for 1st mobile number (60123240066)
}



# 2nd DN:
{
    "status"       : SENT,
    "error-code"   : 20,
    "msisdn"       : 60102200533,
    "msgid"        : "78-1633193001.0602-1"     # 1 refers to DN for 2nd mobile number (60102200533)
}



# 3rd DN:
{
    "status"       : SENT,
    "error-code"   : 20,
    "msisdn"       : 60102410102,
    "msgid"        : "78-1633193001.0602-2"     # 2 refers to DN for 3rd mobile number (60102410102)
}