WhatsApp API V1.4

Video Guide

Last Update: 26th Sep 2020

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 implemented WhatsApp Message in the latest API and bulk sending features.

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 enhanced the DN Status with more failing detail

New features in V1.4:
Bulk Sender List
You can now trigger to send Multiple Recipients with only 1 request
WhatsApp Support
Enable send WhatsApp message with minimum changes
Balance Inquiry
You can now query your Account Balance with our latest API
Delivery Status
Provide more detailed data regarding failure transaction
For User in V1.3 Steps to migrate to V1.4:
  1. Change your API submission from:
    https://sms.360.my/gw/bulk360/v1.3
    change to:
    https://sms.360.my/gw/bulk360/v1.4
  2. Understand how to check Balance and send Multiple Recipients in 1 request

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
  1. Client request send Pre-Approved WhatsApp Template Message [MT] via Bulk360 SMS API V1.4
  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 WhatsApp, Acknowledgement and Reference ID return from WhatsApp
  4. Delivery Notification [DN] return from WhatsApp
  5. Bulk360 return DN with Final Status of the MT Sent, refers to Delivery Notification for returned values
  6. If User response to your template message, WhatsApp will transmit the Incoming Message [MO] to Bulk360
  7. Bulk360 will then transmit the MO by triggering your WhatsApp Incoming Message Hook
  8. 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:
Below table explanation for all Parameters:
# Parameter Description Mandatory Example
1 user Your registered email shall be used here Yes mark@360.my
2 pass Your account password, the same password you used registering in the Bulk360 platform. Note that you shall change the password in your API after you change the account password in sms.360.my. Yes pass001
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
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

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 3 values:
  • status - The real-time delivery status, refer to following table Response Code
  • msisdn - Recipient mobile number
  • msgid - 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
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:
Example of HTTP response returning with parameter 'detail=1':
Example of HTTP response returning with multiple recipients (notice that msg reference ID is longer):
Example of HTTP response returning with multiple recipients and parameter 'detail=1':

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.

Receiving Message (MO)

Mobile Originated (MO) Message refers to a message being sent out from the mobile handset to our system as message reply.

You can enable Message Forwarding in My Configurations > WhatsApp tab by filling in the WhatsApp Incoming Message Hook. New MOs will then be forwarded to your MO URL in real time in following format:

Four parameters return as below:
# Parameter Description Example
1 from The User who reply your message 60123240066
2 to The destination number where User replied 60102200533
3 txnid Transaction reference ID 5515023
4 text Message content replied from user Yes, please send me more info.