Video Guide
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 14 times faster compare to previous version.
Our objective is to make implementation easy and fun with our APIs.
WhatsApp API messages are segregated into 2 types:- Template Message
- Session Message
- Template Message
- Pre-approved message templates for outbound notifications like delivery alerts and appointment reminders. They can not be used for marketing. You must use Template Message if more than 24 hours have elapsed since the user last responded to you. Any other type of message will fail.
- Session Message
- Within 24 hours from the user's last response, all messages sent and received are considered as Session Message. Any message can be send during this 24 hours session including marketing and promotion, video, image, audio, pdf and excel files.
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
- 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
-
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. - Understand and update system based on json object return from our system
Overview of WhatsApp Message Flow
Below figure shows WhatsApp Template and Session Message call flow. The flow, concept and mechanism of Implementing WhatsApp is exactly the same as SMS
- Client request send Pre-Approved WhatsApp Template Message [MT] via Bulk360 SMS API V3.0
-
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 WhatsApp, Acknowledgement and Reference ID return from WhatsApp
- Delivery Notification [DN] return from WhatsApp
- Bulk360 return DN with Final Status of the MT Sent, refers to Delivery Notification for returned values
- If User response to your template message, WhatsApp will transmit the Incoming Message [MO] to Bulk360
- Bulk360 will then transmit the MO by triggering your WhatsApp Incoming Message Hook
- All conversations considered as Session Message within 24 hours from User's last response
Sending WhatsApp Template 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 360 WhatsApp 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 WhatsApp, all POST / GET request shall be submitted to following URL:Actual working example with mandatory parameters:
Actual working example with multilines 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 | whatsapp:60123240066 |
4 | text | The Pre-approved Template Message content. Upon user respond, you will opt into 24 hours period of Session Message. In Session Message, you can send any text including media files | Yes | Message from Bulk360 Gateway |
5 | 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 |
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" : 401,
"desc" : "Invalid Username or password"
}
Example of a successful response for 1 recipient:{
"code" : 200,
"desc" : "OK",
"to" : "whatsapp:60123240066",
"ref" : "78-1633193001.0602"
}
Example of a successful response for 1 recipient (with detail=1):{
"code" : 200,
"desc" : "OK",
"to" : "whatsapp: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 Multi Lingual Messages
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 WhatsApp 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 |
{
"code" : 200,
"desc" : "OK",
"to" : "whatsapp:60123240066",
"ref" : "78-1633193001.0602"
}
Example of HTTP response returning with parameter 'detail=1':{
"code" : 200,
"desc" : "OK",
"to" : "whatsapp:60123240066",
"ref" : "78-1633193001.0602",
"currency" : "MYR",
"balance" : "187.9236"
}
Example of HTTP response returning with multiple recipients:{
"code" : 200,
"desc" : "OK",
"to" : "whatsapp:60123240066,whatsapp:60176655668,whatsapp:60102200533,whatsapp:60102410102,whatsapp:60143600661",
"ref" : "78-1633193001.0602",
"currency" : "MYR",
"balance" : "187.9236"
}
Delivery Notification (DN)
Delivery Notification is the final status of your Message sent.
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:
Three parameters return as below:# | Parameter | Description | Example |
---|---|---|---|
1 | status | Real-time DN Status | DELIVERED or UNDELIVERED |
2 | msisdn | MT recipient mobile number | 60123240066 |
3 | 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.
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 |
# 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=whatsapp:60123240066,whatsapp:60102200533,whatsapp:60102410102&detail=1&text=Message+from+360+Gateway
# Respond from above:
{
"code" : 200,
"desc" : "OK",
"to" : "whatsapp:60123240066,whatsapp:60102200533,whatsapp: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)
}